uuid v7 (#681)

Author: pmccarren

.local/uuid/v7.js

@@ -0,0 +1 @@
+../../v7.js

.prettierignore

@@ -2,3 +2,4 @@
 dist/
 node_modules/
 README.md
+*.sh

AUTHORS

@@ -3,3 +3,4 @@ Christoph Tavan <[email protected]>
 AJ ONeal <[email protected]>
 Vincent Voyer <[email protected]>
 Roman Shtylman <[email protected]>
+Patrick McCarren <[email protected]>

README.md

@@ -7,7 +7,7 @@
 
 For the creation of [RFC4122](https://www.ietf.org/rfc/rfc4122.txt) UUIDs
 
-- **Complete** - Support for RFC4122 version 1, 3, 4, and 5 UUIDs
+- **Complete** - Support for RFC4122 version 1, 3, 4, 5, and 7 UUIDs
 - **Cross-platform** - Support for ...
   - CommonJS, [ECMAScript Modules](#ecmascript-modules) and [CDN builds](#cdn-builds)
   - NodeJS 12+ ([LTS releases](https://github.com/nodejs/Release))
@@ -59,6 +59,7 @@ For timestamp UUIDs, namespace UUIDs, and other options read on ...
 | [`uuid.v3()`](#uuidv3name-namespace-buffer-offset) | Create a version 3 (namespace w/ MD5) UUID |  |
 | [`uuid.v4()`](#uuidv4options-buffer-offset) | Create a version 4 (random) UUID |  |
 | [`uuid.v5()`](#uuidv5name-namespace-buffer-offset) | Create a version 5 (namespace w/ SHA-1) UUID |  |
+| [`uuid.v7()`](#uuidv7options-buffer-offset) | Create a version 7 (Unix Epoch time-based) UUID | `experimental support` |
 | [`uuid.validate()`](#uuidvalidatestr) | Test a string to see if it is a valid UUID | New in `[email protected]` |
 | [`uuid.version()`](#uuidversionstr) | Detect RFC version of a UUID | New in `[email protected]` |
 
@@ -251,6 +252,29 @@ import { v5 as uuidv5 } from 'uuid';
 uuidv5('https://www.w3.org/', uuidv5.URL); // ⇨ 'c106a26a-21bb-5538-8bf2-57095d1976c1'
 ```
 
+### uuid.v7([options[, buffer[, offset]]])
+
+Create an RFC version 7 (random) UUID
+
+|  |  |
+| --- | --- |
+| [`options`] | `Object` with one or more of the following properties: |
+| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) |
+| [`options.random`] | `Array` of 16 random bytes (0-255) |
+| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
+| [`options.seq`] | 31 bit monotonic sequence counter as `Number` between 0 - 0x7fffffff |
+| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
+
+Example:
+
+```javascript
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7(); // ⇨ '01695553-c90c-7aad-9bdd-330d7b3dcb6d'
+```
+
 ### uuid.validate(str)
 
 Test a string to see if it is a valid UUID
@@ -325,6 +349,7 @@ Usage:
   uuid v3 <name> <namespace uuid>
   uuid v4
   uuid v5 <name> <namespace uuid>
+  uuid v7
   uuid --help
 
 Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs

README_js.md

@@ -21,7 +21,7 @@ require('crypto').randomUUID = undefined;
 
 For the creation of [RFC4122](https://www.ietf.org/rfc/rfc4122.txt) UUIDs
 
-- **Complete** - Support for RFC4122 version 1, 3, 4, and 5 UUIDs
+- **Complete** - Support for RFC4122 version 1, 3, 4, 5, and 7 UUIDs
 - **Cross-platform** - Support for ...
   - CommonJS, [ECMAScript Modules](#ecmascript-modules) and [CDN builds](#cdn-builds)
   - NodeJS 12+ ([LTS releases](https://github.com/nodejs/Release))
@@ -73,6 +73,7 @@ For timestamp UUIDs, namespace UUIDs, and other options read on ...
 | [`uuid.v3()`](#uuidv3name-namespace-buffer-offset) | Create a version 3 (namespace w/ MD5) UUID |  |
 | [`uuid.v4()`](#uuidv4options-buffer-offset) | Create a version 4 (random) UUID |  |
 | [`uuid.v5()`](#uuidv5name-namespace-buffer-offset) | Create a version 5 (namespace w/ SHA-1) UUID |  |
+| [`uuid.v7()`](#uuidv7options-buffer-offset) | Create a version 7 (Unix Epoch time-based) UUID | `experimental support` |
 | [`uuid.validate()`](#uuidvalidatestr) | Test a string to see if it is a valid UUID | New in `[email protected]` |
 | [`uuid.version()`](#uuidversionstr) | Detect RFC version of a UUID | New in `[email protected]` |
 
@@ -259,6 +260,29 @@ import { v5 as uuidv5 } from 'uuid';
 uuidv5('https://www.w3.org/', uuidv5.URL); // RESULT
 ```
 
+### uuid.v7([options[, buffer[, offset]]])
+
+Create an RFC version 7 (random) UUID
+
+|  |  |
+| --- | --- |
+| [`options`] | `Object` with one or more of the following properties: |
+| [`options.msecs`] | RFC "timestamp" field (`Number` of milliseconds, unix epoch) |
+| [`options.random`] | `Array` of 16 random bytes (0-255) |
+| [`options.rng`] | Alternative to `options.random`, a `Function` that returns an `Array` of 16 random bytes (0-255) |
+| [`options.seq`] | 31 bit monotonic sequence counter as `Number` between 0 - 0x7fffffff |
+| [`buffer`] | `Array \| Buffer` If specified, uuid will be written here in byte-form, starting at `offset` |
+| [`offset` = 0] | `Number` Index to start writing UUID bytes in `buffer` |
+| _returns_ | UUID `String` if no `buffer` is specified, otherwise returns `buffer` |
+
+Example:
+
+```javascript --run
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7(); // RESULT
+```
+
 ### uuid.validate(str)
 
 Test a string to see if it is a valid UUID
@@ -333,6 +357,7 @@ Usage:
   uuid v3 <name> <namespace uuid>
   uuid v4
   uuid v5 <name> <namespace uuid>
+  uuid v7
   uuid --help
 
 Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs

bundlewatch.config.json

@@ -20,6 +20,8 @@
       "path": "./examples/browser-rollup/dist/v5-size.js",
       "maxSize": "1.5 kB"
     },
+    { "path": "./examples/browser-rollup/dist/v7-size.js", "maxSize": "0.8 kB" },
+
     {
       "path": "./examples/browser-webpack/dist/v1-size.js",
       "maxSize": "1.0 kB"
@@ -35,6 +37,7 @@
     {
       "path": "./examples/browser-webpack/dist/v5-size.js",
       "maxSize": "1.5 kB"
-    }
+    },
+    { "path": "./examples/browser-webpack/dist/v7-size.js", "maxSize": "0.8 kB" }
   ]
 }

examples/benchmark/benchmark.js

@@ -57,12 +57,26 @@ export default function benchmark(uuid, Benchmark) {
       .add('uuid.v4() fill existing array', function () {
         uuid.v4(null, array, 0);
       })
+      .add('uuid.v4() without native generation', function () {
+        uuid.v4({}); // passing an object instead of null bypasses native.randomUUID
+      })
       .add('uuid.v3()', function () {
         uuid.v3('hello.example.com', uuid.v3.DNS);
       })
       .add('uuid.v5()', function () {
         uuid.v5('hello.example.com', uuid.v5.DNS);
       })
+      .add('uuid.v7()', function () {
+        uuid.v7();
+      })
+      .add('uuid.v7() fill existing array', function () {
+        uuid.v7(null, array, 0);
+      })
+      .add('uuid.v7() with defined time', function () {
+        uuid.v7({
+          msecs: 1645557742000,
+        });
+      })
       .on('cycle', function (event) {
         console.log(event.target.toString());
       })

examples/benchmark/package-lock.json

@@ -6,6 +6,7 @@ import {
   v3 as uuidv3,
   v4 as uuidv4,
   v5 as uuidv5,
+  v7 as uuidv7,
   validate as uuidValidate,
   version as uuidVersion,
 } from './node_modules/uuid/dist/esm-browser/index.js';
@@ -15,6 +16,8 @@ console.log('uuidv1()', uuidv1());
 
 console.log('uuidv4()', uuidv4());
 
+console.log('uuidv7()', uuidv7());
+
 // ... using predefined DNS namespace (for domain names)
 console.log('uuidv3() DNS', uuidv3('hello.example.com', uuidv3.DNS));
 
@@ -52,6 +55,7 @@ console.log('Same with default export');
 
 console.log('uuid.v1()', uuid.v1());
 console.log('uuid.v4()', uuid.v4());
+console.log('uuid.v7()', uuid.v7());
 console.log('uuid.v3() DNS', uuid.v3('hello.example.com', uuid.v3.DNS));
 console.log('uuid.v3() URL', uuid.v3('http://example.com/hello', uuid.v3.URL));
 console.log('uuid.v3() MY_NAMESPACE', uuid.v3('Hello, World!', MY_NAMESPACE));

examples/browser-esmodules/example.js

@@ -7,11 +7,12 @@ npm start
 
 Then navigate to `example-*.html`.
 
-The `example-v{1,4}.js` demonstrate that treeshaking works as expected:
+The `example-v{1,4,7}.js` demonstrate that treeshaking works as expected:
 
 ```
 $ du -sh dist/*
  20K  dist/all.js
 8.0K  dist/v1.js
 4.0K  dist/v4.js
+4.0K  dist/v7.js
 ```