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
 ```

examples/browser-rollup/README.md

@@ -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));

examples/browser-rollup/example-all.js

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>UUID esmodule webpack example</title>
+  </head>
+
+  <body>
+    <script type="text/javascript" src="./dist/v7.js"></script>
+  </body>
+</html>

examples/browser-rollup/example-v7.html

@@ -0,0 +1,8 @@
+import { v7 as uuidv7 } from 'uuid';
+
+import testpage from '../utils/testpage';
+
+testpage(function (addTest, done) {
+  addTest('uuidv7()', uuidv7());
+  done();
+});

examples/browser-rollup/example-v7.js

@@ -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>

examples/browser-rollup/example.html

@@ -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,
+  },
 ];

examples/browser-rollup/rollup.config.js

@@ -0,0 +1,3 @@
+import { v7 as uuidv7 } from 'uuid';
+
+uuidv7();

examples/browser-rollup/size-v7.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));