Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

uuid v7 #681

Merged
merged 23 commits into from
Jun 3, 2024
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
0b8f680
feat: implement uuid7 (#580)
pmccarren Jan 22, 2023
a112083
fix: add v7.js to .local (#580)
pmccarren Jan 22, 2023
5a89a92
fix: add v7 to uuid-bin
pmccarren Jan 22, 2023
92bc63a
chore: fix readme anchor
pmccarren Jan 22, 2023
ba6d9cc
chore: use generated readme, remove timestamp arg from uuid-bin v7
pmccarren Jan 22, 2023
3a201c3
fix: typo in uuid regex, add negative test cases
pmccarren Jan 22, 2023
b710c41
fix: do not mutate provided rnds, add v7 unit tests
pmccarren Jan 22, 2023
1a61942
fix: validation test should not pass version 0
pmccarren Jan 22, 2023
bf11212
chore: update package.json description
pmccarren Jan 22, 2023
a17479a
Update src/v7.js
pmccarren Feb 4, 2023
ced5fdc
include uuid v6 and v8 in validation regex
pmccarren Feb 4, 2023
7264c2c
chore: add test:matching script to package.json
pmccarren Feb 4, 2023
2263096
fix: v7 monotonicity and lexicographical sorting
pmccarren Feb 5, 2023
4022ec2
refactor: v7 seq reinitialization
pmccarren Feb 6, 2023
1d5c88a
chore: update v7 README
pmccarren Feb 6, 2023
2626fe2
Merge branch 'uuidjs:main' into uuid7
pmccarren Feb 16, 2023
3cb9acd
chore: fix README_js.md prettier
pmccarren Feb 16, 2023
7f1ceaf
chore: render README.md
pmccarren Feb 16, 2023
33be2ef
Merge branch 'main' into pr/681
broofa Jun 2, 2024
a8dd224
chore: forgot to add updated prettier ignore file
broofa Jun 2, 2024
b9e6efa
docs: update rfc links
broofa Jun 3, 2024
874af5c
chore: regenerate README
broofa Jun 3, 2024
d587e5b
docs: update links
broofa Jun 3, 2024
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .local/uuid/v7.js
1 change: 1 addition & 0 deletions AUTHORS
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ Christoph Tavan <[email protected]>
AJ ONeal <[email protected]>
Vincent Voyer <[email protected]>
Roman Shtylman <[email protected]>
Patrick McCarren <[email protected]>
26 changes: 25 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 | New in `uuid@9.?` |
| [`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]` |

Expand Down Expand Up @@ -248,6 +249,28 @@ 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) |
| [`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-7bad-9bdd-2b0d7b3dcb6d'
```

### uuid.validate(str)

Test a string to see if it is a valid UUID
Expand Down Expand Up @@ -322,6 +345,7 @@ Usage:
uuid v3 <name> <namespace uuid>
uuid v4
uuid v5 <name> <namespace uuid>
uuid v7
pmccarren marked this conversation as resolved.
Show resolved Hide resolved
uuid --help

Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs
Expand Down
26 changes: 25 additions & 1 deletion README_js.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 | New in `uuid@9.?` |
| [`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]` |

Expand Down Expand Up @@ -257,6 +258,28 @@ 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) |
| [`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
Expand Down Expand Up @@ -331,6 +354,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
Expand Down
4 changes: 3 additions & 1 deletion bundlewatch.config.json
Original file line number Diff line number Diff line change
Expand Up @@ -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" }
]
}
14 changes: 14 additions & 0 deletions examples/benchmark/benchmark.js
Original file line number Diff line number Diff line change
Expand Up @@ -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());
})
Expand Down
4 changes: 4 additions & 0 deletions examples/browser-esmodules/example.js
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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));

Expand Down Expand Up @@ -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));
Expand Down
3 changes: 2 additions & 1 deletion examples/browser-rollup/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
4 changes: 4 additions & 0 deletions examples/browser-rollup/example-all.js
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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));

Expand Down Expand Up @@ -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));
Expand Down
12 changes: 12 additions & 0 deletions examples/browser-rollup/example-v7.html
Original file line number Diff line number Diff line change
@@ -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>
8 changes: 8 additions & 0 deletions examples/browser-rollup/example-v7.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
import { v7 as uuidv7 } from 'uuid';

import testpage from '../utils/testpage';

testpage(function (addTest, done) {
addTest('uuidv7()', uuidv7());
done();
});
1 change: 1 addition & 0 deletions examples/browser-rollup/example.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
16 changes: 16 additions & 0 deletions examples/browser-rollup/rollup.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,14 @@ module.exports = [
},
plugins,
},
{
input: './example-v7.js',
output: {
file: 'dist/v7.js',
format: 'iife',
},
plugins,
},

{
input: './size-v1.js',
Expand Down Expand Up @@ -60,4 +68,12 @@ module.exports = [
},
plugins,
},
{
input: './size-v7.js',
output: {
file: 'dist/v7-size.js',
format: 'cjs',
},
plugins,
},
];
3 changes: 3 additions & 0 deletions examples/browser-rollup/size-v7.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
import { v7 as uuidv7 } from 'uuid';

uuidv7();
4 changes: 4 additions & 0 deletions examples/browser-webpack/example-all-require.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const {
v3: uuidv3,
v4: uuidv4,
v5: uuidv5,
v7: uuidv7,
validate: uuidValidate,
version: uuidVersion,
} = uuid;
Expand All @@ -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));

Expand Down Expand Up @@ -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));
Expand Down
4 changes: 4 additions & 0 deletions examples/browser-webpack/example-all.js
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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));

Expand Down Expand Up @@ -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));
Expand Down
12 changes: 12 additions & 0 deletions examples/browser-webpack/example-v7.html
Original file line number Diff line number Diff line change
@@ -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>
9 changes: 9 additions & 0 deletions examples/browser-webpack/example-v7.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import { v7 as uuidv7 } from 'uuid';

import testpage from '../utils/testpage';

testpage(function (addTest, done) {
addTest('uuidv7()', uuidv7());

done();
});
1 change: 1 addition & 0 deletions examples/browser-webpack/example.html
Original file line number Diff line number Diff line change
Expand Up @@ -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>
3 changes: 3 additions & 0 deletions examples/browser-webpack/size-v7.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
import { v7 as uuidv7 } from 'uuid';

uuidv7();
2 changes: 2 additions & 0 deletions examples/browser-webpack/webpack.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading