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

feat: add parse/stringify/validate/version/NIL APIs #479

Merged
merged 22 commits into from Jul 22, 2020
Merged

feat: add parse/stringify/validate/version/NIL APIs #479

merged 22 commits into from Jul 22, 2020

Conversation

ctavan
Copy link
Member

@ctavan ctavan commented Jul 17, 2020

@broofa should we just merge this into master and release as 8.2.0? As far as I can tell it only adds new features, no breaking changes. Or do I miss something?

Closes #475
Closes #478
Closes #480
Closes #481

awwit and others added 4 commits June 2, 2020 08:37
* test: parsing non RFC uuid values

* feat: create validate, version, uuidRegex (and import to public API)

* style: always curly braces

added comments to numberToBytes func
preallocated array in uuidToBytes func

* Update src/regex.js

Co-authored-by: Robert Kieffer <robert@broofa.com>

* Update src/validate.js

Co-authored-by: Robert Kieffer <robert@broofa.com>

* Update src/version.js

Co-authored-by: Robert Kieffer <robert@broofa.com>

* Update test/unit/version.test.js

Co-authored-by: Robert Kieffer <robert@broofa.com>

* feat: throw error when invalid uuid

* test: validate function

* feat: short version of parsing UUID

* fix: remove explicit ie babel target

* Revert "feat: short version of parsing UUID"

This reverts commit d096cc2.

Co-authored-by: Robert Kieffer <robert@broofa.com>
Co-authored-by: Christoph Tavan <dev@tavan.de>
* fix: improved uuidToBytes

* chore: comment tweak

* chore: bump bundlewatch sizes

* fix: uuidToBytes test

* feat: export uuidToBytes, uuidToBytes benchmark

* chore: review comments

* feat: export validate, parse, stringify methods

* chore: stringify unit test and benchmark

* fix: stringify test in browser

* feat: add uuidVersion to rollup exports

* chore: bump bundlewatch limits

* chore: tweak function name

* test: enable browserstack.console setting

* fix: revert padStart

* fix: pr review comments

* fix: no Array.from in IE11

* improvement: hardcode namespace length

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

Co-authored-by: Christoph Tavan <dev@tavan.de>
Co-authored-by: Linus Unnebäck <linus@folkdatorn.se>
@ctavan ctavan requested a review from broofa July 17, 2020 12:48
@ctavan
Copy link
Member Author

ctavan commented Jul 17, 2020

BTW we still need documentation in the README.

@broofa
Copy link
Member

broofa commented Jul 17, 2020

@ctavan: Agreed. As you said, there's no breaking changes.

I'll update the README. Also, I'm going to go ahead and add a NIL_UUID constant as well, per discussion in #475. In thinking further, I don't see much down side to that.

@ctavan ctavan mentioned this pull request Jul 17, 2020
@broofa
Copy link
Member

broofa commented Jul 17, 2020

@ctavan Updated the README.

  • Added docs for new methods
  • Added API Summary section to show the API surface in one glance.
  • Reduced "quick start" section down to just the bare minimum for v4 generation since that's the 80+% use case...
  • ... and users can refer to the examples in the API docs for how to create other versions of UUID.
  • Put method args, returns, and errors into tables

Note: I also made one minor functional change. stringify() now validate()s generated uiud strings to ensure they're valid. Previously you could hand it any bytes and it would blindly stringify, even if the result wouldn't pass validate(). I feel this is in keeping with the "this module follows the RFC" philosophy we've had but it wouldn't surprise me if/when someone complains about it.

Copy link
Member

@broofa broofa left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, I'm happy with this, but maybe get a sanity check review from @TrySound?

@broofa broofa requested a review from TrySound July 19, 2020 18:41
Copy link
Member

@TrySound TrySound left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything looks great

Copy link
Member Author

@ctavan ctavan left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@broofa this looks awesome, thanks a lot 👏

I've made some minor consistency adjustments to the README myself.

I still have 3 questions that we should address before merging this. Once merged I'd like to release this as a beta release and ask the people who wanted these features to try them out. Upon positive feedback I'll make the 8.2 release.

}

testParseAndStringify();
testGeneration();
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will these tests run in parallel? Shouldn't we rather ensure that they are run in series?

Copy link
Member

@broofa broofa Jul 21, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will these tests run in parallel? Shouldn't we rather ensure that they are run in series?

I believe Benchmark.js runs synchronously, so these do run in series. (At least, that's what I see when I do cd examples/benchmark; node benchmark.js.)

rollup.config.js Show resolved Hide resolved
src/stringify.js Outdated Show resolved Hide resolved
@ctavan
Copy link
Member Author

ctavan commented Jul 21, 2020

Changes look good. What about my comment regarding the benchmark parallelism?

@ctavan ctavan changed the title V9 feat: add parse/stringify/validate/version/NIL APIs Jul 22, 2020
@ctavan ctavan merged commit 0e6c10b into master Jul 22, 2020
@ctavan ctavan deleted the v9 branch July 22, 2020 20:32
@ctavan ctavan mentioned this pull request Jul 22, 2020
@zaggino
Copy link

zaggino commented Jul 31, 2020

@broofa @ctavan I upgraded package from 8.2.0 to 8.3.0 and this should be marked as a breaking change (major) update. Before the routine would work:

import { v5 as uuidv5 } from 'uuid';

const UUID_V5_NAMESPACE = '00112233-4455-6677-8899-aabbccddeeff';

function getUuidHash(str: string) {
  return uuidv5(str, UUID_V5_NAMESPACE);
}

Now after update it throws an error:

TypeError: Invalid UUID

@ctavan
Copy link
Member Author

ctavan commented Jul 31, 2020

@zaggino the RFC requires the namespace to be a valid UUID. It's true that up to 8.2.0 we did not verify that the passed namespace was a truly valid UUID, and we added this check in 8.3.0. However this should rather be considered a bug fix than a breaking change since the behavior before was counter the RFC.

Can you update your code to pass only valid UUIDs as namespaces? A valid UUID must match this regex:

export default /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;

I.e. it must either be the NIL UUID or it has the UUID version after the second hyphen (in your example there's a 6 which is not a valid UUID version) and one of 89ab after the third hypen (you have an 8 in your example here, so this would be valid).

@zaggino
Copy link

zaggino commented Jul 31, 2020

I did update the code, but my concern was that a ^8.0.0 dependency which we had caused a break all over the application when a package-lock.json was refreshed.

From the RFC perspective, I agree on fixing this, but from a user-developer perspective - I never noticed any buggy behaviour before this, so was there ever an actual bug when a namespace which was not a 100% proper uuid was used?

@ctavan
Copy link
Member Author

ctavan commented Jul 31, 2020

I think this can be a serious interoperability issue: if you have other libraries or programming languages that already do the right thing by validating the passed namespace UUIDs then the UUIDs generated from malformed namespaces with old versions of this library won’t be compatible with those other libraries/languages.

So as long as everything that ever has to deal with the v5 UUIDs generated off of bad namespace ids will always use the same flawed library there’s probably no problem, but as soon as you need to be interoperable this might cause very subtle and hard-to-find bugs.

@ctavan
Copy link
Member Author

ctavan commented Jul 31, 2020

All that said I agree that it is maybe not the best developer experience to introduce such a change in a minor version bump. Unfortunately it’s out now and too late. Our assessment that this should be a non-breaking change for most developers was apparently wrong. We‘ll be more careful in the future. I’m sorry for the inconvenience.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

toBytes isUuid Reopened discussion: parse/unparse uuid Support nil or empty uuid
5 participants