uuid v7 by pmccarren · Pull Request #681 · uuidjs/uuid

pmccarren · 2023-01-22T00:49:50Z

UUID V7

This PR implements UUID V7, ~~closing~~ ref #580

V7 is implemented, tested and documented and ready for review! No changes to the other versions were made.

Relevant RFC documents:

Benchmarks

V7 appears as fast as V4 when not using native crypto.randomUUID generation.

Results:

Starting. Tests take ~1 minute to run ...
uuid.stringify() x 1,450,855 ops/sec ±2.12% (88 runs sampled)
uuid.parse() x 2,350,677 ops/sec ±1.19% (88 runs sampled)
---

uuid.v1() x 3,585,680 ops/sec ±0.86% (92 runs sampled)
uuid.v1() fill existing array x 9,229,031 ops/sec ±0.50% (93 runs sampled)
uuid.v4() x 13,834,376 ops/sec ±3.34% (84 runs sampled)
uuid.v4() fill existing array x 3,833,619 ops/sec ±1.51% (84 runs sampled)
uuid.v4() without native generation x 2,395,572 ops/sec ±1.27% (91 runs sampled)
uuid.v3() x 268,797 ops/sec ±1.32% (86 runs sampled)
uuid.v5() x 287,899 ops/sec ±1.12% (92 runs sampled)
uuid.v7() x 2,764,344 ops/sec ±0.95% (93 runs sampled)
uuid.v7() fill existing array x 2,801,443 ops/sec ±5.48% (84 runs sampled)
uuid.v7() with defined time x 3,223,107 ops/sec ±1.14% (89 runs sampled)
Fastest is uuid.v4()

TODO:

preserve monotonicity
Add V7 type definitions to DefinitelyTyped

note, husky pre-commit hook was bypassed for this commit

broofa

Thanks for the contribution @pmccarren ccarren. This looks promising!

In addition to the inline comments, can you add a unit test alongside https://github.com/uuidjs/uuid/blob/main/test/unit/v1.test.js, with similar assertions. Specifically, I'd like to see similar tests for sort order, uniqueness, and options handling. (And anything else you think may be relevant.)

The sorting will be of particular interest, since producing UUIDS that sort the same whether sorted by timestamp or lexicographically was pretty much the whole point of version 7. 😄

Note: This should not close #580, as the new RFC adds v6 and v8 formats, too, as well as the MAX_UUID constant. v7 is definitely the majority of what's needed, but we'll want to keep 580 open until we fill in the remaining items.

Lastly, the new RFC is still making it's way through the review process. I don't expect substantive changes at this point, so this is an appropriate time to be adding this. But as I noted in 580, I think it's prudent to go with an experimental version release tag of some sort.

@ctavan: Thoughts on how best to accept this? Should we create a v9-experimental branch that we merge this into rather than master? Then publish experimental releases from that?

README.md

src/regex.js

src/uuid-bin.js

src/v7.js

pmccarren · 2023-01-22T23:02:26Z

@broofa - glad to lend a hand! I appreciate your time reviewing the implementation.

This PR has been updated with your suggested changes, most notably:

reworked buffer management so rnds is not mutated
added v7 unit test coverage
fixed README generation (via npm run docs)

In regards to sorting, I've been considering a few different approaches and while not presently implemented in this PR, I absolutely agree it should be :) I'll work on implementing this as well the associated unit tests.

src/regex.js

src/v7.js

LinusU

Code looks good 👍

Lastly, the new RFC is still making it's way through the review process.

Thoughts on how best to accept this? Should we create a v9-experimental branch that we merge this into rather than master? Then publish experimental releases from that?

Personally think that we should keep this PR open until the spec has been ratified. If we merge into a v9 branch that would stop us from making a v9 release until that has happened, and that might potentially be a long time?

I think that it would be nice to backport the "version 2 is valid" bugfix right away to the current release though?

ctavan · 2023-01-25T07:44:06Z

Thanks an lot for the contribution!

I initially thought this new feature could land in the v9 release, but given we’re broadening the validation regex it’s a breaking change and we’ll have to bump the major version.

I think it would be nice to somehow release it as a prerelease so that people have a chance to try it and provide feedback, but I think our current release and branching process is not yet ready for multiple active major releases. If anyone’s willing to take a look at this I’m happy to support (we were considering better automation for this for a while… #636).

I agree however, that we should not release this in a public major release until the draft has been accepted.

src/regex.js

src/v7.js

broofa · 2023-01-25T23:52:09Z

Note: I've just created the rfc4122bis branch off main as a place to land this (and set it as the target for this PR). As @ctavan says, we haven't worked through the deploy & publish pipeline for non-main branches yet, so we'll have to figure that out.

Wish I could give you an ETA for that, but it's not been a priority for either of us. As he says... "Help Wanted".

Co-authored-by: Linus Unnebäck <linus@folkdatorn.se>

broofa

@ctavan @LinusU Any other comments? If not, I'd like to get this merged (pending @pmccarren commiting his suggested change for the regex to allow 1-8).

Regarding the plan for the rfc4122bis branch, I've created a project to capture the remaining work, with brief notes on possible implementation details.

Honestly, there's not all that much left... if anyone is feeling inspired. ;-)

Lastly, thoughts on inviting Patrick to join the UUIDJS org? He's done some solid work here that's much appreciated, and seappears to have good street cred. If people could weigh in on that idea (including you, Patrick), we can move forward or not as appropriate. [cc'ing @TrySound here]

pmccarren · 2023-02-04T18:55:59Z

@broofa just merged the 1-8 regex update. I'm close to done with implementing monotonic generation - I'd prefer to merge once that's wrapped. Will be buttoned up in a day or two.

As for UUIDJS Org, I'll let my work speak for itself but will add that if you'll have me I'll be an active participant :)

pmccarren · 2023-02-06T05:41:34Z

@broofa I just finished adding monotonic support, and it's ready for review! Took a bit of finesse but I'm rather happy with how it turned out. In addition to the monotonicity related unit tests, I manually tested sorting preservation during generation of 100M uuids.

couple of sequence counter implementation notes:

when additional generations occur inside the same millisecond, we use a dedicated 31 bits as an incrementing sequence counter. Referred to as Fixed-Length Dedicated Counter Bits (Method 1) in the draft RFC.
seq is 31 bits and (re)initialized from the random data pool whenever the clock advances/changes. as the seq is initialized randomly, for nominal usage there is a significant amount (74 bits) of randomness in a given v7 uuid.
when the sequence counter rolls over we increment the internal date by 1 millisecond and continue. this accepts the tradeoff of minor clock drift for lexicographical sorting in substantial batch id generation workloads.
if the internal date ever exceeds 10 seconds beyond system time, both the date and seq are hard reset.
lexicographical sorting is preserved up to (2^31)*10000 generations for a provided millisecond.
the seq is stored as 31 bits. the 12 high bits and 19 low bits are stored separately in the uuid to preserve sorting while maintaining a large enough counter size

Pending review, I believe this PR is ready to go now!

mbrimmer83 · 2024-05-10T09:02:08Z

Rumor has it uuid v7 is now part of the proposed standard What would it take to get this over the finish line?

ryan-keswick · 2024-05-26T07:09:57Z

Any updates on this?

broofa · 2024-06-03T01:55:10Z

Did another review pass. Pushed a couple minor documentation tweaks to update things now that RFC9562 is official.

@ctavan: In the interests of moving forward with 9562, I'm merging this. If there are questions or concerns, we can address those in followup PRs.

@pmccarren: Thanks for the great work on this. My apologies for letting this stagnate for so long. Now that 9562 is official, my goal is to get this pushed out ASAP.

ctavan · 2024-06-03T05:01:43Z

I‘m all for it, thanks for taking care!

But let’s make use of the conventional commit message format in the squash commits so we get proper autogenerated changelogs.

broofa · 2024-06-03T05:19:27Z

let’s make use of the conventional commit message format in the squash commits

Ugh... I keep screwing that up. :-(

ctavan · 2024-06-03T05:38:22Z

Does GitHub have an option to run actions (commitlint) before squash merges?

broofa · 2024-06-03T09:34:18Z

There's probably a way, but... 🤷

pmccarren · 2024-06-03T15:07:40Z

@broofa and @ctavan I appreciate your time in reviewing and assisting with the PR. I'm excited we're collectively one step closer to uuid7 being widely available :)

If there is a need for assistance, I have time I can dedicate towards experimental deploys. Just let me know if it'll be helpful, and I'm happy to dive in.

broofa · 2024-06-03T17:09:19Z

@pmccarren That'd be awesome. On the deploy front, there's two nuts we'd like to crack:

Enforce Conventional Commits™ on every commit that goes onto the main branch. (witness my fumbling the message on this PR)
Automate the deploy process so we're not manually publishing from our laptops.

We haven't tackled the former yet, but if you know a way to do that, we're all for it.

For the latter, I put up #725 a couple years ago before getting distracted by other things. The main goal there was to get away from our current ad-hoc release process that has us creating PRs just to update package.json#version, and running standard-version and npm publish manually on our laptops. Specifically, I wanted to automate the following:

Update CHANGELOG with notes for all relevant changes
Bump package.json#version based on Conventional Commit message semantics
Create git tag for release
Run npm publish in a workflow

release-please is (I think) still a good choice for that but I haven't followed development of that project so I'm not sure what bells-and-whistles may have been added. If you can get that working, that'd be great. Or if there's another option you think would work better I'm open to suggestions.

I've sent you an invite to the uuidjs org here. Let me know if there are permissions you need here or on NPM for this work. (Obviously we'll need to be careful about what gets npm-published.)

And thank you for stepping up to help (again).

sachinjnd · 2024-06-08T07:23:10Z

@broofa / @pmccarren Now that the changes for uuid v7 are merged, what's the plan for release on npm?

ctavan · 2024-06-08T11:14:00Z

See #760

This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [uuid](https://github.com/uuidjs/uuid) | dependencies | major | [`^9.0.0` -> `^10.0.0`](https://renovatebot.com/diffs/npm/uuid/9.0.1/10.0.0) | --- ### Release Notes <details> <summary>uuidjs/uuid (uuid)</summary> ### [`v10.0.0`](https://github.com/uuidjs/uuid/blob/HEAD/CHANGELOG.md#1000-2024-06-07) [Compare Source](uuidjs/uuid@v9.0.1...v10.0.0) ##### ⚠ BREAKING CHANGES - update node support (drop node@12, node@14, add node@20) ([#750](uuidjs/uuid#750)) ##### Features - support support rfc9562 MAX uuid (new in RFC9562) ([#714](uuidjs/uuid#714)) ([0385cd3](uuidjs/uuid@0385cd3)) - support rfc9562 v6 uuids ([#754](uuidjs/uuid#754)) ([c4ed13e](uuidjs/uuid@c4ed13e)) - support rfc9562 v7 uuids ([#681](uuidjs/uuid#681)) ([db76a12](uuidjs/uuid@db76a12)) - update node support matrix (only support node 16-20) ([#750](uuidjs/uuid#750)) ([883b163](uuidjs/uuid@883b163)) - support rfc9562 v8 uuids ([#759](uuidjs/uuid#759)) ([35a5342](uuidjs/uuid@35a5342)) ##### Bug Fixes - revert "perf: remove superfluous call to toLowerCase ([#677](uuidjs/uuid#677))" ([#738](uuidjs/uuid#738)) ([e267b90](uuidjs/uuid@e267b90)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or rename PR to start with "rebase!". 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

pmccarren added 4 commits January 21, 2023 19:36

feat: implement uuid7 (uuidjs#580)

0b8f680

fix: add v7.js to .local (uuidjs#580)

a112083

note, husky pre-commit hook was bypassed for this commit

fix: add v7 to uuid-bin

5a89a92

chore: fix readme anchor

92bc63a

broofa reviewed Jan 22, 2023

View reviewed changes

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

src/regex.js Outdated Show resolved Hide resolved

src/uuid-bin.js Outdated Show resolved Hide resolved

src/v7.js Outdated Show resolved Hide resolved

pmccarren added 5 commits January 22, 2023 12:48

chore: use generated readme, remove timestamp arg from uuid-bin v7

ba6d9cc

fix: typo in uuid regex, add negative test cases

3a201c3

fix: do not mutate provided rnds, add v7 unit tests

b710c41

fix: validation test should not pass version 0

1a61942

chore: update package.json description

bf11212

LinusU reviewed Jan 25, 2023

View reviewed changes

src/regex.js Outdated Show resolved Hide resolved

LinusU reviewed Jan 25, 2023

View reviewed changes

src/v7.js Outdated Show resolved Hide resolved

LinusU reviewed Jan 25, 2023

View reviewed changes

broofa requested changes Jan 25, 2023

View reviewed changes

src/regex.js Outdated Show resolved Hide resolved

src/v7.js Outdated Show resolved Hide resolved

broofa changed the base branch from main to rfc4122bis January 25, 2023 23:46

Update src/v7.js

a17479a

Co-authored-by: Linus Unnebäck <linus@folkdatorn.se>

broofa mentioned this pull request Feb 4, 2023

Validate new versions (6-8) #683

Closed

broofa added the bis label Feb 4, 2023

broofa approved these changes Feb 4, 2023

View reviewed changes

include uuid v6 and v8 in validation regex

ced5fdc

pmccarren added 4 commits February 4, 2023 13:25

chore: add test:matching script to package.json

7264c2c

fix: v7 monotonicity and lexicographical sorting

2263096

refactor: v7 seq reinitialization

4022ec2

chore: update v7 README

1d5c88a

pmccarren requested a review from broofa February 9, 2023 23:19

broofa mentioned this pull request May 30, 2024

uuidv6 has been officially adopted by the IETF #748

Closed

broofa added 2 commits June 2, 2024 16:38

Merge branch 'main' into pr/681

33be2ef

chore: forgot to add updated prettier ignore file

a8dd224

broofa changed the base branch from rfc4122bis to main June 3, 2024 00:10

broofa removed the bis label Jun 3, 2024

broofa mentioned this pull request Jun 3, 2024

Tracking Issue: RFC 9562 / uuid@10 #749

Closed

9 tasks

broofa added 3 commits June 2, 2024 17:41

docs: update rfc links

b9e6efa

chore: regenerate README

874af5c

docs: update links

d587e5b

broofa merged commit db76a12 into uuidjs:main Jun 3, 2024

clemens-msupply mentioned this pull request Jun 6, 2024

Use uuid v7 instead of v4 msupply-foundation/open-msupply#4052

Merged

pmccarren mentioned this pull request Jun 6, 2024

feat: add TypeScript typings #654

Closed

11 tasks

robinpokorny mentioned this pull request Jun 14, 2024

v7: passing options.msecs results in zero-value timestamp #764

Closed

2 tasks

Rosangel49 mentioned this pull request May 14, 2025

changelog mentions issues that arent linked #871

Closed

Uh oh!

Conversation

pmccarren commented Jan 22, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

UUID V7

Benchmarks

Uh oh!

broofa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pmccarren commented Jan 22, 2023

Uh oh!

Uh oh!

Uh oh!

LinusU left a comment

Choose a reason for hiding this comment

Uh oh!

ctavan commented Jan 25, 2023

Uh oh!

Uh oh!

Uh oh!

broofa commented Jan 25, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

broofa left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmccarren commented Feb 4, 2023

Uh oh!

pmccarren commented Feb 6, 2023

Uh oh!

mbrimmer83 commented May 10, 2024

Uh oh!

ryan-keswick commented May 26, 2024

Uh oh!

broofa commented Jun 3, 2024

Uh oh!

ctavan commented Jun 3, 2024

Uh oh!

broofa commented Jun 3, 2024

Uh oh!

ctavan commented Jun 3, 2024

Uh oh!

broofa commented Jun 3, 2024

Uh oh!

pmccarren commented Jun 3, 2024

Uh oh!

broofa commented Jun 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sachinjnd commented Jun 8, 2024

Uh oh!

ctavan commented Jun 8, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

13 participants

pmccarren commented Jan 22, 2023 •

edited

Loading

broofa left a comment •

edited

Loading

broofa commented Jan 25, 2023 •

edited

Loading

broofa left a comment •

edited

Loading

broofa commented Jun 3, 2024 •

edited

Loading