Uuid7 (#1)

* feat: implement uuid7 (uuidjs#580) * fix: add v7.js to .local (uuidjs#580) note, husky pre-commit hook was bypassed for this commit * fix: add v7 to uuid-bin * chore: fix readme anchor * chore: use generated readme, remove timestamp arg from uuid-bin v7 * fix: typo in uuid regex, add negative test cases * fix: do not mutate provided rnds, add v7 unit tests * fix: validation test should not pass version 0 * chore: update package.json description * Update src/v7.js Co-authored-by: Linus Unnebäck <[email protected]> * include uuid v6 and v8 in validation regex * chore: add test:matching script to package.json * fix: v7 monotonicity and lexicographical sorting * refactor: v7 seq reinitialization * chore: update v7 README --------- Co-authored-by: Patrick McCarren <[email protected]> Co-authored-by: Linus Unnebäck <[email protected]>
csmith23 · Feb 7, 2023 · 9e3799a · 9e3799a
1 parent eca69af
commit 9e3799a
Show file tree

Hide file tree

Showing 37 changed files with 534 additions and 9 deletions.
diff --git a/.local/uuid/v7.js b/.local/uuid/v7.js
@@ -0,0 +1 @@
+../../v7.js
diff --git a/AUTHORS b/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]>
diff --git a/README.md b/README.md
@@ -6,7 +6,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)
   - Node 12, 14, 16, 18
@@ -56,6 +56,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]` |
 
@@ -248,6 +249,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
@@ -322,6 +346,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

diff --git a/README_js.md b/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)
   - Node 12, 14, 16, 18
@@ -71,6 +71,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]` |
 
@@ -257,6 +258,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
@@ -331,6 +355,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

diff --git a/bundlewatch.config.json b/bundlewatch.config.json
@@ -4,10 +4,12 @@
     { "path": "./examples/browser-rollup/dist/v3-size.js", "maxSize": "2.1 kB" },
     { "path": "./examples/browser-rollup/dist/v4-size.js", "maxSize": "0.7 kB" },
     { "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" },
     { "path": "./examples/browser-webpack/dist/v3-size.js", "maxSize": "2.1 kB" },
     { "path": "./examples/browser-webpack/dist/v4-size.js", "maxSize": "0.7 kB" },
-    { "path": "./examples/browser-webpack/dist/v5-size.js", "maxSize": "1.5 kB" }
+    { "path": "./examples/browser-webpack/dist/v5-size.js", "maxSize": "1.5 kB" },
+    { "path": "./examples/browser-webpack/dist/v7-size.js", "maxSize": "0.8 kB" }
   ]
 }
diff --git a/examples/benchmark/benchmark.js b/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());
       })

diff --git a/examples/browser-esmodules/example.js b/examples/browser-esmodules/example.js
@@ -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));

diff --git a/examples/browser-rollup/README.md b/examples/browser-rollup/README.md
@@ -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
 ```
diff --git a/examples/browser-rollup/example-all.js b/examples/browser-rollup/example-all.js
@@ -6,6 +6,7 @@ import {
   v3 as uuidv3,
   v4 as uuidv4,
   v5 as uuidv5,
+  v7 as uuidv7,
   validate as uuidValidate,
   version as uuidVersion,
 } from 'uuid';
@@ -20,6 +21,8 @@ testpage(function (addTest, done) {
 
   addTest('uuidv4()', uuidv4());
 
+  addTest('uuidv7()', uuidv7());
+
   // ... using predefined DNS namespace (for domain names)
   addTest('uuidv3() DNS', uuidv3('hello.example.com', uuidv3.DNS));
 
@@ -57,6 +60,7 @@ testpage(function (addTest, done) {
 
   addTest('uuid.v1()', uuid.v1());
   addTest('uuid.v4()', uuid.v4());
+  addTest('uuid.v7()', uuid.v7());
   addTest('uuid.v3() DNS', uuid.v3('hello.example.com', uuid.v3.DNS));
   addTest('uuid.v3() URL', uuid.v3('http://example.com/hello', uuid.v3.URL));
   addTest('uuid.v3() MY_NAMESPACE', uuid.v3('Hello, World!', MY_NAMESPACE));

diff --git a/examples/browser-rollup/example-v7.html b/examples/browser-rollup/example-v7.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>UUID esmodule webpack example</title>
+</head>
+
+<body>
+  <script type="text/javascript" src="./dist/v7.js"></script>
+</body>
+
+</html>
diff --git a/examples/browser-rollup/example-v7.js b/examples/browser-rollup/example-v7.js
@@ -0,0 +1,8 @@
+import { v7 as uuidv7 } from 'uuid';
+
+import testpage from '../utils/testpage';
+
+testpage(function (addTest, done) {
+  addTest('uuidv7()', uuidv7());
+  done();
+});
diff --git a/examples/browser-rollup/example.html b/examples/browser-rollup/example.html
@@ -3,4 +3,5 @@
 <p>Please open the Developer Console to view output</p>
 <script type="text/javascript" src="./dist/v1.js"></script>
 <script type="text/javascript" src="./dist/v4.js"></script>
+<script type="text/javascript" src="./dist/v7.js"></script>
 <script type="text/javascript" src="./dist/all.js"></script>
diff --git a/examples/browser-rollup/rollup.config.js b/examples/browser-rollup/rollup.config.js
@@ -27,6 +27,14 @@ module.exports = [
     },
     plugins,
   },
+  {
+    input: './example-v7.js',
+    output: {
+      file: 'dist/v7.js',
+      format: 'iife',
+    },
+    plugins,
+  },
 
   {
     input: './size-v1.js',
@@ -60,4 +68,12 @@ module.exports = [
     },
     plugins,
   },
+  {
+    input: './size-v7.js',
+    output: {
+      file: 'dist/v7-size.js',
+      format: 'cjs',
+    },
+    plugins,
+  },
 ];
diff --git a/examples/browser-rollup/size-v7.js b/examples/browser-rollup/size-v7.js
@@ -0,0 +1,3 @@
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7();
diff --git a/examples/browser-webpack/example-all-require.js b/examples/browser-webpack/example-all-require.js
@@ -7,6 +7,7 @@ const {
   v3: uuidv3,
   v4: uuidv4,
   v5: uuidv5,
+  v7: uuidv7,
   validate: uuidValidate,
   version: uuidVersion,
 } = uuid;
@@ -20,6 +21,8 @@ testpage(function (addTest, done) {
 
   addTest('uuidv4()', uuidv4());
 
+  addTest('uuidv7()', uuidv7());
+
   // ... using predefined DNS namespace (for domain names)
   addTest('uuidv3() DNS', uuidv3('hello.example.com', uuidv3.DNS));
 
@@ -57,6 +60,7 @@ testpage(function (addTest, done) {
 
   addTest('uuid.v1()', uuid.v1());
   addTest('uuid.v4()', uuid.v4());
+  addTest('uuid.v7()', uuid.v7());
   addTest('uuid.v3() DNS', uuid.v3('hello.example.com', uuid.v3.DNS));
   addTest('uuid.v3() URL', uuid.v3('http://example.com/hello', uuid.v3.URL));
   addTest('uuid.v3() MY_NAMESPACE', uuid.v3('Hello, World!', MY_NAMESPACE));

diff --git a/examples/browser-webpack/example-all.js b/examples/browser-webpack/example-all.js
@@ -6,6 +6,7 @@ import {
   v3 as uuidv3,
   v4 as uuidv4,
   v5 as uuidv5,
+  v7 as uuidv7,
   validate as uuidValidate,
   version as uuidVersion,
 } from 'uuid';
@@ -20,6 +21,8 @@ testpage(function (addTest, done) {
 
   addTest('uuidv4()', uuidv4());
 
+  addTest('uuidv7()', uuidv7());
+
   // ... using predefined DNS namespace (for domain names)
   addTest('uuidv3() DNS', uuidv3('hello.example.com', uuidv3.DNS));
 
@@ -57,6 +60,7 @@ testpage(function (addTest, done) {
 
   addTest('uuid.v1()', uuid.v1());
   addTest('uuid.v4()', uuid.v4());
+  addTest('uuid.v7()', uuid.v7());
   addTest('uuid.v3() DNS', uuid.v3('hello.example.com', uuid.v3.DNS));
   addTest('uuid.v3() URL', uuid.v3('http://example.com/hello', uuid.v3.URL));
   addTest('uuid.v3() MY_NAMESPACE', uuid.v3('Hello, World!', MY_NAMESPACE));

diff --git a/examples/browser-webpack/example-v7.html b/examples/browser-webpack/example-v7.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+	<title>UUID esmodule webpack example</title>
+</head>
+
+<body>
+	<script type="text/javascript" src="./dist/v7.js"></script>
+</body>
+
+</html>
diff --git a/examples/browser-webpack/example-v7.js b/examples/browser-webpack/example-v7.js
@@ -0,0 +1,9 @@
+import { v7 as uuidv7 } from 'uuid';
+
+import testpage from '../utils/testpage';
+
+testpage(function (addTest, done) {
+  addTest('uuidv7()', uuidv7());
+
+  done();
+});
diff --git a/examples/browser-webpack/example.html b/examples/browser-webpack/example.html
@@ -3,4 +3,5 @@
 <p>Please open the Developer Console to view output</p>
 <script type="text/javascript" src="./dist/v1.js"></script>
 <script type="text/javascript" src="./dist/v4.js"></script>
+<script type="text/javascript" src="./dist/v7.js"></script>
 <script type="text/javascript" src="./dist/all.js"></script>
diff --git a/examples/browser-webpack/size-v7.js b/examples/browser-webpack/size-v7.js
@@ -0,0 +1,3 @@
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7();
diff --git a/examples/browser-webpack/webpack.config.js b/examples/browser-webpack/webpack.config.js
@@ -7,11 +7,13 @@ module.exports = {
     allRequire: './example-all-require.js',
     v1: './example-v1.js',
     v4: './example-v4.js',
+    v7: './example-v7.js',
 
     'v1-size': './size-v1.js',
     'v3-size': './size-v3.js',
     'v4-size': './size-v4.js',
     'v5-size': './size-v5.js',
+    'v7-size': './size-v7.js',
   },
   // Webpack now produces builds that are incompatible with IE11:
   // https://webpack.js.org/migrate/5/#turn-off-es2015-syntax-in-runtime-code-if-necessary
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { v7 as uuidv7 } from 'uuid';

		uuidv7();