From 628715c073b145de7f24bd2e9b600b0a00e29f42 Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 07:43:12 +0500
Subject: [PATCH 1/7] crypto: implement randomUUIDv7()

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
---
 doc/api/crypto.md                         | 28 +++++++
 lib/crypto.js                             |  2 +
 lib/internal/crypto/random.js             | 58 +++++++++++++++
 test/parallel/test-crypto-randomuuidv7.js | 91 +++++++++++++++++++++++
 4 files changed, 179 insertions(+)
 create mode 100644 test/parallel/test-crypto-randomuuidv7.js

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index fb80671b8bd8a6..12a81e0d27fb03 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5826,6 +5826,33 @@ added:
 Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a
 cryptographic pseudorandom number generator.
 
+### `crypto.randomUUIDv7()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {string}
+
+Generates a random [RFC 9562][] version 7 UUID. The UUID contains a millisecond
+precision Unix timestamp in the most significant 48 bits, followed by
+cryptographically secure random bits for the remaining fields, making it
+suitable for use as a database key with time-based sorting.
+
+```mjs
+import { randomUUIDv7 } from 'node:crypto';
+
+console.log(randomUUIDv7());
+// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
+```
+
+```cjs
+const { randomUUIDv7 } = require('node:crypto');
+
+console.log(randomUUIDv7());
+// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
+```
+
 ### `crypto.scrypt(password, salt, keylen[, options], callback)`
 
 <!-- YAML
@@ -6861,6 +6888,7 @@ See the [list of SSL OP Flags][] for details.
 [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
 [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
+[RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562.txt
 [RFC 5280]: https://www.rfc-editor.org/rfc/rfc5280.txt
 [RFC 7517]: https://www.rfc-editor.org/rfc/rfc7517.txt
 [RFC 8032]: https://www.rfc-editor.org/rfc/rfc8032.txt
diff --git a/lib/crypto.js b/lib/crypto.js
index 4290989f3cd6b1..ac4b0a33efb8ab 100644
--- a/lib/crypto.js
+++ b/lib/crypto.js
@@ -56,6 +56,7 @@ const {
   randomFillSync,
   randomInt,
   randomUUID,
+  randomUUIDv7,
 } = require('internal/crypto/random');
 const {
   argon2,
@@ -220,6 +221,7 @@ module.exports = {
   randomFillSync,
   randomInt,
   randomUUID,
+  randomUUIDv7,
   scrypt,
   scryptSync,
   sign: signOneShot,
diff --git a/lib/internal/crypto/random.js b/lib/internal/crypto/random.js
index 72ac4b72ac0825..bac9521c2d0f88 100644
--- a/lib/internal/crypto/random.js
+++ b/lib/internal/crypto/random.js
@@ -11,6 +11,7 @@ const {
   BigIntPrototypeToString,
   DataView,
   DataViewPrototypeGetUint8,
+  DateNow,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
   MathMin,
@@ -414,6 +415,62 @@ function randomUUID(options) {
   return disableEntropyCache ? getUnbufferedUUID() : getBufferedUUID();
 }
 
+// Implements an RFC 9562 version 7 UUID (time-ordered).
+// Layout (128 bits total):
+//   48 bits  - unix_ts_ms: UTC timestamp in milliseconds
+//    4 bits  - version: 0b0111 (7)
+//   12 bits  - rand_a: random
+//    2 bits  - variant: 0b10
+//   62 bits  - rand_b: random
+
+let uuidV7Buffer;
+
+function randomUUIDv7() {
+  uuidV7Buffer ??= secureBuffer(16);
+  if (uuidV7Buffer === undefined)
+    throw new ERR_OPERATION_FAILED('Out of memory');
+
+  // Fill all 16 bytes with random data first.
+  randomFillSync(uuidV7Buffer);
+
+  // Write 48-bit timestamp (ms since Unix epoch) into bytes 0-5, big-endian.
+  const now = DateNow();
+  uuidV7Buffer[0] = (now / 0x10000000000) & 0xff;
+  uuidV7Buffer[1] = (now / 0x100000000) & 0xff;
+  uuidV7Buffer[2] = (now / 0x1000000) & 0xff;
+  uuidV7Buffer[3] = (now / 0x10000) & 0xff;
+  uuidV7Buffer[4] = (now / 0x100) & 0xff;
+  uuidV7Buffer[5] = now & 0xff;
+
+  // Set version (7) in byte 6 high nibble, keep rand_a in low nibble.
+  uuidV7Buffer[6] = (uuidV7Buffer[6] & 0x0f) | 0x70;
+
+  // Set variant (0b10) in byte 8 high 2 bits, keep rand_b in low 6 bits.
+  uuidV7Buffer[8] = (uuidV7Buffer[8] & 0x3f) | 0x80;
+
+  const kHexBytes = getHexBytes();
+  return kHexBytes[uuidV7Buffer[0]] +
+    kHexBytes[uuidV7Buffer[1]] +
+    kHexBytes[uuidV7Buffer[2]] +
+    kHexBytes[uuidV7Buffer[3]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[4]] +
+    kHexBytes[uuidV7Buffer[5]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[6]] +
+    kHexBytes[uuidV7Buffer[7]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[8]] +
+    kHexBytes[uuidV7Buffer[9]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[10]] +
+    kHexBytes[uuidV7Buffer[11]] +
+    kHexBytes[uuidV7Buffer[12]] +
+    kHexBytes[uuidV7Buffer[13]] +
+    kHexBytes[uuidV7Buffer[14]] +
+    kHexBytes[uuidV7Buffer[15]];
+}
+
 function createRandomPrimeJob(type, size, options) {
   validateObject(options, 'options');
 
@@ -611,6 +668,7 @@ module.exports = {
   randomInt,
   getRandomValues,
   randomUUID,
+  randomUUIDv7,
   generatePrime,
   generatePrimeSync,
 };
diff --git a/test/parallel/test-crypto-randomuuidv7.js b/test/parallel/test-crypto-randomuuidv7.js
new file mode 100644
index 00000000000000..bedeb463b32ce0
--- /dev/null
+++ b/test/parallel/test-crypto-randomuuidv7.js
@@ -0,0 +1,91 @@
+'use strict';
+
+const common = require('../common');
+
+if (!common.hasCrypto)
+  common.skip('missing crypto');
+
+const assert = require('assert');
+const {
+  randomUUIDv7,
+} = require('crypto');
+
+// Basic return type and format checks.
+{
+  const uuid = randomUUIDv7();
+  assert.strictEqual(typeof uuid, 'string');
+  assert.strictEqual(uuid.length, 36);
+
+  // UUIDv7 format: xxxxxxxx-xxxx-7xxx-[89ab]xxx-xxxxxxxxxxxx
+  assert.match(
+    uuid,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  );
+}
+
+// Check version and variant bits.
+{
+  const uuid = randomUUIDv7();
+
+  // Version 7: byte 6 high nibble should be 0x7.
+  assert.strictEqual(
+    Buffer.from(uuid.slice(14, 16), 'hex')[0] & 0xf0, 0x70,
+  );
+
+  // Variant: byte 8 high 2 bits should be 0b10.
+  assert.strictEqual(
+    Buffer.from(uuid.slice(19, 21), 'hex')[0] & 0b1100_0000, 0b1000_0000,
+  );
+}
+
+// Uniqueness: generate many UUIDs and verify no duplicates.
+{
+  const seen = new Set();
+  for (let i = 0; i < 1000; i++) {
+    const uuid = randomUUIDv7();
+    assert(!seen.has(uuid), `Duplicate UUID generated: ${uuid}`);
+    seen.add(uuid);
+  }
+}
+
+// Timestamp: the embedded timestamp should approximate Date.now().
+{
+  const before = Date.now();
+  const uuid = randomUUIDv7();
+  const after = Date.now();
+
+  // Extract the 48-bit timestamp from the UUID.
+  // Bytes 0-3 (chars 0-8) and bytes 4-5 (chars 9-13, skipping the dash).
+  const hex = uuid.replace(/-/g, '');
+  const timestampHex = hex.slice(0, 12); // first 48 bits = 12 hex chars
+  const timestamp = parseInt(timestampHex, 16);
+
+  assert(timestamp >= before, `Timestamp ${timestamp} < before ${before}`);
+  assert(timestamp <= after, `Timestamp ${timestamp} > after ${after}`);
+}
+
+// Monotonicity: UUIDs generated in sequence should sort lexicographically
+// within the same millisecond or across milliseconds.
+{
+  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}`);
+    prev = curr;
+  }
+}
+
+// Ensure randomUUIDv7 takes no arguments (or ignores them gracefully).
+{
+  const uuid = randomUUIDv7();
+  assert.match(
+    uuid,
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+  );
+}

From 274b11a63dfce92acea246a3ea1952660f0b0a34 Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 08:34:40 +0500
Subject: [PATCH 2/7] crypto: refactor randomUUIDv7() to use serializeUUID for
 improved readability

---
 lib/internal/crypto/random.js | 31 ++++---------------------------
 1 file changed, 4 insertions(+), 27 deletions(-)

diff --git a/lib/internal/crypto/random.js b/lib/internal/crypto/random.js
index bac9521c2d0f88..47d224e32ef638 100644
--- a/lib/internal/crypto/random.js
+++ b/lib/internal/crypto/random.js
@@ -430,10 +430,8 @@ function randomUUIDv7() {
   if (uuidV7Buffer === undefined)
     throw new ERR_OPERATION_FAILED('Out of memory');
 
-  // Fill all 16 bytes with random data first.
   randomFillSync(uuidV7Buffer);
 
-  // Write 48-bit timestamp (ms since Unix epoch) into bytes 0-5, big-endian.
   const now = DateNow();
   uuidV7Buffer[0] = (now / 0x10000000000) & 0xff;
   uuidV7Buffer[1] = (now / 0x100000000) & 0xff;
@@ -442,34 +440,13 @@ function randomUUIDv7() {
   uuidV7Buffer[4] = (now / 0x100) & 0xff;
   uuidV7Buffer[5] = now & 0xff;
 
-  // Set version (7) in byte 6 high nibble, keep rand_a in low nibble.
   uuidV7Buffer[6] = (uuidV7Buffer[6] & 0x0f) | 0x70;
 
-  // Set variant (0b10) in byte 8 high 2 bits, keep rand_b in low 6 bits.
   uuidV7Buffer[8] = (uuidV7Buffer[8] & 0x3f) | 0x80;
-
-  const kHexBytes = getHexBytes();
-  return kHexBytes[uuidV7Buffer[0]] +
-    kHexBytes[uuidV7Buffer[1]] +
-    kHexBytes[uuidV7Buffer[2]] +
-    kHexBytes[uuidV7Buffer[3]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[4]] +
-    kHexBytes[uuidV7Buffer[5]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[6]] +
-    kHexBytes[uuidV7Buffer[7]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[8]] +
-    kHexBytes[uuidV7Buffer[9]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[10]] +
-    kHexBytes[uuidV7Buffer[11]] +
-    kHexBytes[uuidV7Buffer[12]] +
-    kHexBytes[uuidV7Buffer[13]] +
-    kHexBytes[uuidV7Buffer[14]] +
-    kHexBytes[uuidV7Buffer[15]];
-}
+  
+  const result = serializeUUID(uuidV7Buffer);
+  return result;
+}   
 
 function createRandomPrimeJob(type, size, options) {
   validateObject(options, 'options');

From 87dd2ac0d3f88e1c7cb31f14673d2b67535a74cd Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 09:25:26 +0500
Subject: [PATCH 3/7] test: remove redundant checks for UUID version and
 variant bits

---
 test/parallel/test-crypto-randomuuidv7.js | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/test/parallel/test-crypto-randomuuidv7.js b/test/parallel/test-crypto-randomuuidv7.js
index bedeb463b32ce0..d7316d37d630f2 100644
--- a/test/parallel/test-crypto-randomuuidv7.js
+++ b/test/parallel/test-crypto-randomuuidv7.js
@@ -10,7 +10,6 @@ const {
   randomUUIDv7,
 } = require('crypto');
 
-// Basic return type and format checks.
 {
   const uuid = randomUUIDv7();
   assert.strictEqual(typeof uuid, 'string');
@@ -23,22 +22,18 @@ const {
   );
 }
 
-// Check version and variant bits.
 {
   const uuid = randomUUIDv7();
 
-  // Version 7: byte 6 high nibble should be 0x7.
   assert.strictEqual(
     Buffer.from(uuid.slice(14, 16), 'hex')[0] & 0xf0, 0x70,
   );
 
-  // Variant: byte 8 high 2 bits should be 0b10.
   assert.strictEqual(
     Buffer.from(uuid.slice(19, 21), 'hex')[0] & 0b1100_0000, 0b1000_0000,
   );
 }
 
-// Uniqueness: generate many UUIDs and verify no duplicates.
 {
   const seen = new Set();
   for (let i = 0; i < 1000; i++) {
@@ -64,8 +59,6 @@ const {
   assert(timestamp <= after, `Timestamp ${timestamp} > after ${after}`);
 }
 
-// Monotonicity: UUIDs generated in sequence should sort lexicographically
-// within the same millisecond or across milliseconds.
 {
   let prev = randomUUIDv7();
   for (let i = 0; i < 100; i++) {

From 828867d8d1eaaa7ca9209d9db984eca66c5db2d8 Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 13:25:30 +0500
Subject: [PATCH 4/7] crypto: update randomUUIDv7() to construct UUID string
 directly from bytes

---
 lib/internal/crypto/random.js | 36 +++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

diff --git a/lib/internal/crypto/random.js b/lib/internal/crypto/random.js
index 47d224e32ef638..0c5a94fe3d3d9b 100644
--- a/lib/internal/crypto/random.js
+++ b/lib/internal/crypto/random.js
@@ -14,6 +14,7 @@ const {
   DateNow,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
+  MathFloor,
   MathMin,
   NumberIsNaN,
   NumberIsSafeInteger,
@@ -433,19 +434,38 @@ function randomUUIDv7() {
   randomFillSync(uuidV7Buffer);
 
   const now = DateNow();
-  uuidV7Buffer[0] = (now / 0x10000000000) & 0xff;
-  uuidV7Buffer[1] = (now / 0x100000000) & 0xff;
-  uuidV7Buffer[2] = (now / 0x1000000) & 0xff;
-  uuidV7Buffer[3] = (now / 0x10000) & 0xff;
-  uuidV7Buffer[4] = (now / 0x100) & 0xff;
+  uuidV7Buffer[0] = MathFloor(now / 0x10000000000) & 0xff;
+  uuidV7Buffer[1] = MathFloor(now / 0x100000000) & 0xff;
+  uuidV7Buffer[2] = MathFloor(now / 0x1000000) & 0xff;
+  uuidV7Buffer[3] = MathFloor(now / 0x10000) & 0xff;
+  uuidV7Buffer[4] = MathFloor(now / 0x100) & 0xff;
   uuidV7Buffer[5] = now & 0xff;
 
   uuidV7Buffer[6] = (uuidV7Buffer[6] & 0x0f) | 0x70;
 
   uuidV7Buffer[8] = (uuidV7Buffer[8] & 0x3f) | 0x80;
-  
-  const result = serializeUUID(uuidV7Buffer);
-  return result;
+
+  const kHexBytes = getHexBytes();
+  return kHexBytes[uuidV7Buffer[0]] +
+    kHexBytes[uuidV7Buffer[1]] +
+    kHexBytes[uuidV7Buffer[2]] +
+    kHexBytes[uuidV7Buffer[3]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[4]] +
+    kHexBytes[uuidV7Buffer[5]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[6]] +
+    kHexBytes[uuidV7Buffer[7]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[8]] +
+    kHexBytes[uuidV7Buffer[9]] +
+    '-' +
+    kHexBytes[uuidV7Buffer[10]] +
+    kHexBytes[uuidV7Buffer[11]] +
+    kHexBytes[uuidV7Buffer[12]] +
+    kHexBytes[uuidV7Buffer[13]] +
+    kHexBytes[uuidV7Buffer[14]] +
+    kHexBytes[uuidV7Buffer[15]];
 }   
 
 function createRandomPrimeJob(type, size, options) {

From e3a4a06dd618eb9e195c2526bcce1e95b2dbc0df Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 16:16:23 +0500
Subject: [PATCH 5/7] crypto: update randomUUIDv7() to accept options for
 disabling entropy cache

---
 doc/api/crypto.md                         |  8 ++-
 lib/internal/crypto/random.js             | 87 +++++++++++------------
 test/parallel/test-crypto-randomuuidv7.js | 28 ++++++++
 3 files changed, 76 insertions(+), 47 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 12a81e0d27fb03..1fdb86c59f634d 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5826,12 +5826,18 @@ added:
 Generates a random [RFC 4122][] version 4 UUID. The UUID is generated using a
 cryptographic pseudorandom number generator.
 
-### `crypto.randomUUIDv7()`
+### `crypto.randomUUIDv7([options])`
 
 <!-- YAML
 added: REPLACEME
 -->
 
+* `options` {Object}
+  * `disableEntropyCache` {boolean} By default, to improve performance,
+    Node.js generates and caches enough
+    random data to generate up to 128 random UUIDs. To generate a UUID
+    without using the cache, set `disableEntropyCache` to `true`.
+    **Default:** `false`.
 * Returns: {string}
 
 Generates a random [RFC 9562][] version 7 UUID. The UUID contains a millisecond
diff --git a/lib/internal/crypto/random.js b/lib/internal/crypto/random.js
index 0c5a94fe3d3d9b..748add2f711295 100644
--- a/lib/internal/crypto/random.js
+++ b/lib/internal/crypto/random.js
@@ -14,7 +14,6 @@ const {
   DateNow,
   FunctionPrototypeBind,
   FunctionPrototypeCall,
-  MathFloor,
   MathMin,
   NumberIsNaN,
   NumberIsSafeInteger,
@@ -361,7 +360,7 @@ function getHexBytes() {
   return hexBytesCache;
 }
 
-function serializeUUID(buf, offset = 0) {
+function serializeUUID(buf, offset = 0, version = 0x40, variant = 0x80) {
   const kHexBytes = getHexBytes();
   // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   return kHexBytes[buf[offset]] +
@@ -372,10 +371,10 @@ function serializeUUID(buf, offset = 0) {
     kHexBytes[buf[offset + 4]] +
     kHexBytes[buf[offset + 5]] +
     '-' +
-    kHexBytes[(buf[offset + 6] & 0x0f) | 0x40] +
+    kHexBytes[(buf[offset + 6] & 0x0f) | version] +
     kHexBytes[buf[offset + 7]] +
     '-' +
-    kHexBytes[(buf[offset + 8] & 0x3f) | 0x80] +
+    kHexBytes[(buf[offset + 8] & 0x3f) | variant] +
     kHexBytes[buf[offset + 9]] +
     '-' +
     kHexBytes[buf[offset + 10]] +
@@ -416,56 +415,52 @@ function randomUUID(options) {
   return disableEntropyCache ? getUnbufferedUUID() : getBufferedUUID();
 }
 
-// Implements an RFC 9562 version 7 UUID (time-ordered).
-// Layout (128 bits total):
-//   48 bits  - unix_ts_ms: UTC timestamp in milliseconds
-//    4 bits  - version: 0b0111 (7)
-//   12 bits  - rand_a: random
-//    2 bits  - variant: 0b10
-//   62 bits  - rand_b: random
+let uuidV7Data;
+let uuidV7NotBuffered;
+let uuidV7Batch = 0;
 
-let uuidV7Buffer;
+function writeTimestamp(buf, offset) {
+  const now = DateNow();
+  const msb = now / (2 ** 32);
+  buf[offset] = msb >>> 8;
+  buf[offset + 1] = msb;
+  buf[offset + 2] = now >>> 24;
+  buf[offset + 3] = now >>> 16;
+  buf[offset + 4] = now >>> 8;
+  buf[offset + 5] = now;
+}
 
-function randomUUIDv7() {
-  uuidV7Buffer ??= secureBuffer(16);
-  if (uuidV7Buffer === undefined)
+function getBufferedUUIDv7() {
+  uuidV7Data ??= secureBuffer(16 * kBatchSize);
+  if (uuidV7Data === undefined)
     throw new ERR_OPERATION_FAILED('Out of memory');
 
-  randomFillSync(uuidV7Buffer);
+  if (uuidV7Batch === 0) randomFillSync(uuidV7Data);
+  uuidV7Batch = (uuidV7Batch + 1) % kBatchSize;
+  const offset = uuidV7Batch * 16;
+  writeTimestamp(uuidV7Data, offset);
+  return serializeUUID(uuidV7Data, offset, 0x70);
+}
 
-  const now = DateNow();
-  uuidV7Buffer[0] = MathFloor(now / 0x10000000000) & 0xff;
-  uuidV7Buffer[1] = MathFloor(now / 0x100000000) & 0xff;
-  uuidV7Buffer[2] = MathFloor(now / 0x1000000) & 0xff;
-  uuidV7Buffer[3] = MathFloor(now / 0x10000) & 0xff;
-  uuidV7Buffer[4] = MathFloor(now / 0x100) & 0xff;
-  uuidV7Buffer[5] = now & 0xff;
+function getUnbufferedUUIDv7() {
+  uuidV7NotBuffered ??= secureBuffer(16);
+  if (uuidV7NotBuffered === undefined)
+    throw new ERR_OPERATION_FAILED('Out of memory');
+  randomFillSync(uuidV7NotBuffered, 6);
+  writeTimestamp(uuidV7NotBuffered, 0);
+  return serializeUUID(uuidV7NotBuffered, 0, 0x70);
+}
 
-  uuidV7Buffer[6] = (uuidV7Buffer[6] & 0x0f) | 0x70;
+function randomUUIDv7(options) {
+  if (options !== undefined)
+    validateObject(options, 'options');
+  const {
+    disableEntropyCache = false,
+  } = options || kEmptyObject;
 
-  uuidV7Buffer[8] = (uuidV7Buffer[8] & 0x3f) | 0x80;
+  validateBoolean(disableEntropyCache, 'options.disableEntropyCache');
 
-  const kHexBytes = getHexBytes();
-  return kHexBytes[uuidV7Buffer[0]] +
-    kHexBytes[uuidV7Buffer[1]] +
-    kHexBytes[uuidV7Buffer[2]] +
-    kHexBytes[uuidV7Buffer[3]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[4]] +
-    kHexBytes[uuidV7Buffer[5]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[6]] +
-    kHexBytes[uuidV7Buffer[7]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[8]] +
-    kHexBytes[uuidV7Buffer[9]] +
-    '-' +
-    kHexBytes[uuidV7Buffer[10]] +
-    kHexBytes[uuidV7Buffer[11]] +
-    kHexBytes[uuidV7Buffer[12]] +
-    kHexBytes[uuidV7Buffer[13]] +
-    kHexBytes[uuidV7Buffer[14]] +
-    kHexBytes[uuidV7Buffer[15]];
+  return disableEntropyCache ? getUnbufferedUUIDv7() : getBufferedUUIDv7();
 }   
 
 function createRandomPrimeJob(type, size, options) {
diff --git a/test/parallel/test-crypto-randomuuidv7.js b/test/parallel/test-crypto-randomuuidv7.js
index d7316d37d630f2..99d052f356721c 100644
--- a/test/parallel/test-crypto-randomuuidv7.js
+++ b/test/parallel/test-crypto-randomuuidv7.js
@@ -82,3 +82,31 @@ const {
     /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
   );
 }
+
+{
+  const uuidv7Regex =
+    /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+  assert.match(randomUUIDv7({ disableEntropyCache: true }), uuidv7Regex);
+  assert.match(randomUUIDv7({ disableEntropyCache: true }), uuidv7Regex);
+  assert.match(randomUUIDv7({ disableEntropyCache: true }), uuidv7Regex);
+  assert.match(randomUUIDv7({ disableEntropyCache: true }), uuidv7Regex);
+
+  assert.throws(() => randomUUIDv7(1), {
+    code: 'ERR_INVALID_ARG_TYPE',
+  });
+
+  assert.throws(() => randomUUIDv7({ disableEntropyCache: '' }), {
+    code: 'ERR_INVALID_ARG_TYPE',
+  });
+}
+
+{
+  for (let n = 0; n < 130; n++) {
+    const uuid = randomUUIDv7();
+    assert.match(
+      uuid,
+      /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
+    );
+  }
+}

From 8ddc406af3592e5db8c65888657ef8529408560a Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 17:18:50 +0500
Subject: [PATCH 6/7] crypto: address review feedback for randomUUIDv7

- Make version/variant required params in serializeUUID
- Share buffer pools (uuidData/uuidNotBuffered) between v4 and v7

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
---
 doc/api/crypto.md             | 14 --------------
 lib/internal/crypto/random.js | 36 ++++++++++++++++-------------------
 2 files changed, 16 insertions(+), 34 deletions(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 1fdb86c59f634d..f0d295901ac59d 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -5845,20 +5845,6 @@ precision Unix timestamp in the most significant 48 bits, followed by
 cryptographically secure random bits for the remaining fields, making it
 suitable for use as a database key with time-based sorting.
 
-```mjs
-import { randomUUIDv7 } from 'node:crypto';
-
-console.log(randomUUIDv7());
-// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
-```
-
-```cjs
-const { randomUUIDv7 } = require('node:crypto');
-
-console.log(randomUUIDv7());
-// e.g. '019d45ea-151f-780b-82a6-d097b39db62a'
-```
-
 ### `crypto.scrypt(password, salt, keylen[, options], callback)`
 
 <!-- YAML
diff --git a/lib/internal/crypto/random.js b/lib/internal/crypto/random.js
index 748add2f711295..c324b2292b2fb8 100644
--- a/lib/internal/crypto/random.js
+++ b/lib/internal/crypto/random.js
@@ -360,7 +360,7 @@ function getHexBytes() {
   return hexBytesCache;
 }
 
-function serializeUUID(buf, offset = 0, version = 0x40, variant = 0x80) {
+function serializeUUID(buf, version, variant, offset = 0) {
   const kHexBytes = getHexBytes();
   // xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   return kHexBytes[buf[offset]] +
@@ -392,7 +392,7 @@ function getBufferedUUID() {
 
   if (uuidBatch === 0) randomFillSync(uuidData);
   uuidBatch = (uuidBatch + 1) % kBatchSize;
-  return serializeUUID(uuidData, uuidBatch * 16);
+  return serializeUUID(uuidData, 0x40, 0x80, uuidBatch * 16);
 }
 
 function getUnbufferedUUID() {
@@ -400,7 +400,7 @@ function getUnbufferedUUID() {
   if (uuidNotBuffered === undefined)
     throw new ERR_OPERATION_FAILED('Out of memory');
   randomFillSync(uuidNotBuffered);
-  return serializeUUID(uuidNotBuffered);
+  return serializeUUID(uuidNotBuffered, 0x40, 0x80);
 }
 
 function randomUUID(options) {
@@ -415,10 +415,6 @@ function randomUUID(options) {
   return disableEntropyCache ? getUnbufferedUUID() : getBufferedUUID();
 }
 
-let uuidV7Data;
-let uuidV7NotBuffered;
-let uuidV7Batch = 0;
-
 function writeTimestamp(buf, offset) {
   const now = DateNow();
   const msb = now / (2 ** 32);
@@ -431,24 +427,24 @@ function writeTimestamp(buf, offset) {
 }
 
 function getBufferedUUIDv7() {
-  uuidV7Data ??= secureBuffer(16 * kBatchSize);
-  if (uuidV7Data === undefined)
+  uuidData ??= secureBuffer(16 * kBatchSize);
+  if (uuidData === undefined)
     throw new ERR_OPERATION_FAILED('Out of memory');
 
-  if (uuidV7Batch === 0) randomFillSync(uuidV7Data);
-  uuidV7Batch = (uuidV7Batch + 1) % kBatchSize;
-  const offset = uuidV7Batch * 16;
-  writeTimestamp(uuidV7Data, offset);
-  return serializeUUID(uuidV7Data, offset, 0x70);
+  if (uuidBatch === 0) randomFillSync(uuidData);
+  uuidBatch = (uuidBatch + 1) % kBatchSize;
+  const offset = uuidBatch * 16;
+  writeTimestamp(uuidData, offset);
+  return serializeUUID(uuidData, 0x70, 0x80, offset);
 }
 
 function getUnbufferedUUIDv7() {
-  uuidV7NotBuffered ??= secureBuffer(16);
-  if (uuidV7NotBuffered === undefined)
+  uuidNotBuffered ??= secureBuffer(16);
+  if (uuidNotBuffered === undefined)
     throw new ERR_OPERATION_FAILED('Out of memory');
-  randomFillSync(uuidV7NotBuffered, 6);
-  writeTimestamp(uuidV7NotBuffered, 0);
-  return serializeUUID(uuidV7NotBuffered, 0, 0x70);
+  randomFillSync(uuidNotBuffered, 6);
+  writeTimestamp(uuidNotBuffered, 0);
+  return serializeUUID(uuidNotBuffered, 0x70, 0x80);
 }
 
 function randomUUIDv7(options) {
@@ -461,7 +457,7 @@ function randomUUIDv7(options) {
   validateBoolean(disableEntropyCache, 'options.disableEntropyCache');
 
   return disableEntropyCache ? getUnbufferedUUIDv7() : getBufferedUUIDv7();
-}   
+}
 
 function createRandomPrimeJob(type, size, options) {
   validateObject(options, 'options');

From 49dac434cf22d4be3c83ec533cb9b3f4c54642d4 Mon Sep 17 00:00:00 2001
From: nabeel378 <mohammadnabeeljameel@gmail.com>
Date: Thu, 2 Apr 2026 18:39:20 +0500
Subject: [PATCH 7/7] docs: update RFC 9562 link in crypto documentation

Signed-off-by: nabeel378 <mohammadnabeeljameel@gmail.com>
---
 doc/api/crypto.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index f0d295901ac59d..55b948aac50db5 100644
--- a/doc/api/crypto.md
+++ b/doc/api/crypto.md
@@ -6880,10 +6880,10 @@ See the [list of SSL OP Flags][] for details.
 [RFC 4055]: https://www.rfc-editor.org/rfc/rfc4055.txt
 [RFC 4122]: https://www.rfc-editor.org/rfc/rfc4122.txt
 [RFC 5208]: https://www.rfc-editor.org/rfc/rfc5208.txt
-[RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562.txt
 [RFC 5280]: https://www.rfc-editor.org/rfc/rfc5280.txt
 [RFC 7517]: https://www.rfc-editor.org/rfc/rfc7517.txt
 [RFC 8032]: https://www.rfc-editor.org/rfc/rfc8032.txt
+[RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562.txt
 [Web Crypto API documentation]: webcrypto.md
 [`BN_is_prime_ex`]: https://www.openssl.org/docs/man1.1.1/man3/BN_is_prime_ex.html
 [`Buffer`]: buffer.md