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

Rename default method #35

Merged
merged 15 commits into from
Nov 29, 2019
Merged
26 changes: 7 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,15 +42,15 @@ developers from security pitfalls.

The UUID standard library provides an API for generating RFC 4122 identifiers.

The default export of the UUID library is the
[Version 4 Algorithm](https://tools.ietf.org/html/rfc4122#section-4.4), and returns the string
representation _(as described in RFC-4122)_.
The only export of the UUID library that is initially supported is a method which implements the
ctavan marked this conversation as resolved.
Show resolved Hide resolved
[version 4 "Algorithm for Creating a UUID from Truly Random or Pseudo-Random Numbers"](https://tools.ietf.org/html/rfc4122#section-4.4),
and returns the string representation _(as described in RFC-4122)_.

```js
// We're not yet certain as to how the API will be accessed (whether it's in the global, or a
// future built-in module), and this will be part of the investigative process as we continue
// working on the proposal.
uuid(); // "52e6953d-edbe-4953-be2e-65ed3836b2f0"
randomUUID(); // "52e6953d-edbe-4953-be2e-65ed3836b2f0"
```

### `Math.getRandomValues()`
Expand All @@ -72,10 +72,10 @@ single mockable (see [#25](https://github.com/tc39/proposal-uuid/issues/25)) sou

## Out of scope

Algorithms described in RFC 4122 other than Version 4 are not initially supported.
Algorithms described in RFC 4122 other than version 4 are not initially supported.

Statistics we've collected ([see analysis/README.md](./analysis/README.md)) indicate that the
Version 4 algorithm is most widely used:
version 4 algorithm is most widely used:

| Algorithm Version | Repo Count | % | Weighted by Watch Count | % |
| ----------------- | ---------- | ----- | ----------------------- | ----- |
Expand All @@ -87,7 +87,7 @@ Version 4 algorithm is most widely used:
### Regarding other UUID versions

While there is utility in other UUID versions, we are advocating starting with a minimal API
surface that supports a large percentage of users _(the string representation of Version 4 UUIDs)._
surface that supports a large percentage of users _(the string representation of version 4 UUIDs)._

If research and/or user feedback later indicates that additional functionality, such as versions 1,
3, and 5 UUIDs, would add value, this proposal does not preclude these additions.
Expand Down Expand Up @@ -127,18 +127,6 @@ implementations have led to
It is for this reason that this spec mandates that any random numbers used come from a
"cryptographically secure" source, thereby (hopefully) avoiding such issues.

### Why does the standard library API treat `v4` UUIDs as a default?
bcoe marked this conversation as resolved.
Show resolved Hide resolved

An analysis of popular Open Source projects that were using `v1` UUIDs has shown that the majority
of identified projects did not have a compelling reason for using `v1` UUIDs, and with education
were willing to migrate to `v4` UUIDs.

We have reached out to the developers of the 6 most popular (based on watch count) actively
maintained GitHub projects where this was the case and all of them accepted our pull requests.

Please refer to [analysis/README.md](./analysis/README.md#accidental-v1-usage) for more
information.

### But aren't v1 UUIDs better because they are guaranteed to be unique?

As an oversimplification, `v1` UUIDs consist of two parts: A high-precision `timestamp` and a
Expand Down