{"id":13527483,"url":"https://github.com/tc39/proposal-uuid","last_synced_at":"2025-10-06T06:05:30.275Z","repository":{"id":53170206,"uuid":"179867028","full_name":"tc39/proposal-uuid","owner":"tc39","description":"UUID proposal for ECMAScript (Stage 1)","archived":false,"fork":false,"pushed_at":"2021-04-02T19:23:32.000Z","size":53,"stargazers_count":463,"open_issues_count":10,"forks_count":7,"subscribers_count":38,"default_branch":"master","last_synced_at":"2025-03-30T02:07:16.948Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tc39.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-06T17:47:16.000Z","updated_at":"2024-09-11T15:39:16.000Z","dependencies_parsed_at":"2022-09-12T18:00:52.701Z","dependency_job_id":null,"html_url":"https://github.com/tc39/proposal-uuid","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-uuid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-uuid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-uuid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tc39%2Fproposal-uuid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tc39","download_url":"https://codeload.github.com/tc39/proposal-uuid/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:01:48.971Z","updated_at":"2025-10-06T06:05:25.240Z","avatar_url":"https://github.com/tc39.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# ECMAScript proposal: JavaScript standard library UUID\n\n**\u0026#x26a0;\u0026#xfe0f;\u0026#x26a0;\u0026#xfe0f; UPDATE 2021: This proposal is now being pursued at:\nhttps://github.com/WICG/uuid \u0026#x26a0;\u0026#xfe0f;\u0026#x26a0;\u0026#xfe0f;**\n\nStatus: Stage 1\n\n## Authors\n\n- Benjamin Coe ([@bcoe](https://github.com/bcoe))\n- Robert Kieffer ([@broofa](https://github.com/broofa))\n- Christoph Tavan ([@ctavan](https://github.com/ctavan))\n\n## Synopsis\n\nThe [JavaScript standard library][standard-library-proposal] UUID describes an API for generating\ncharacter encoded Universally Unique Identifiers (UUID) based on [IETF RFC 4122][rfc-4122],\navailable for import in JavaScript engines.\n\n## Motivation\n\n### UUID generation is an extremely common software requirement\n\nThe [`uuid` module](https://www.npmjs.com/package/uuid) on npm currently receives some\n[64,000,000 monthly downloads](https://npm-stat.com/charts.html?package=uuid) and is relied on by\nover 2,600,000 repositories (as of June 2019).\n\nThe ubiquitous nature of the `uuid` module demonstrates that UUID generation is a common\nrequirement for JavaScript software applications, making the functionality a good candidate for the\nstandard library.\n\n### Developers \"re-inventing the wheel\" is potentially harmful\n\nDevelopers who have not been exposed to RFC 4122 might naturally opt to invent their own approaches\nto UUID generation, potentially using `Math.random()` (in [TIFU by using `Math.random()`][tifu]\nthere's an in-depth discussion of why a Cryptographically-Secure-Pseudo-Random-Number-Generator\n(_CSPRNG_) should be used when generating UUIDs).\n\nIntroducing a UUID standard library, which dictates that a CSPRNG must be used, helps protect\ndevelopers from security pitfalls.\n\n## Overview\n\n### UUID API\n\nThe UUID standard library provides an API for generating RFC 4122 identifiers.\n\nThe only export of the UUID library that is initially supported is `randomUUID()`, a method which\nimplements the\n[version 4 \"Algorithm for Creating a UUID from Truly Random or Pseudo-Random Numbers\"](https://tools.ietf.org/html/rfc4122#section-4.4),\nand returns the string representation _(as described in RFC-4122)_.\n\n```js\n// We're not yet certain as to how the API will be accessed (whether it's in the global, or a\n// future built-in module), and this will be part of the investigative process as we continue\n// working on the proposal.\nrandomUUID(); // \"52e6953d-edbe-4953-be2e-65ed3836b2f0\"\n```\n\n### `Math.getRandomValues()`\n\n`Math.getRandomValues()` exposes an identical API to the\n[W3C `crypto.getRandomValues()`](https://www.w3.org/TR/WebCryptoAPI/#Crypto-method-getRandomValues)\nrecommendation. With the same guarantees, regarding the quality of randomness:\n\n\u003e Implementations should generate cryptographically random values using well-established\n\u003e cryptographic pseudo-random number generators seeded with high-quality entropy, such as from an\n\u003e operating-system entropy source (e.g., \"/dev/urandom\"). This specification provides no\n\u003e lower-bound on the information theoretic entropy present in cryptographically random values, but\n\u003e implementations should make a best effort to provide as much entropy as practicable.\n\u003e\n\u003e - [WebCryptoAPI 10.1. Description](https://www.w3.org/TR/WebCryptoAPI/#Crypto-description)\n\n`Math.getRandomValues()` will act as the foundation for implementing UUID algorithms, providing a\nsingle mockable (see [#25](https://github.com/tc39/proposal-uuid/issues/25)) source of randomness.\n\n## Out of scope\n\nAlgorithms described in RFC 4122 other than version 4 are not initially supported.\n\nStatistics we've collected ([see analysis/README.md](./analysis/README.md)) indicate that the\nversion 4 algorithm is most widely used:\n\n| Algorithm Version | Repo Count | %     | Weighted by Watch Count | %     |\n| ----------------- | ---------- | ----- | ----------------------- | ----- |\n| v4                | 4315       | 77.0% | 149802                  | 89.5% |\n| v1                | 1228       | 21.9% | 16219                   | 9.7%  |\n| v5                | 51         | 0.9%  | 1290                    | 0.8%  |\n| v3                | 11         | 0.2%  | 116                     | 0.1%  |\n\n### Regarding other UUID versions\n\nWhile there is utility in other UUID versions, we are advocating starting with a minimal API\nsurface that supports a large percentage of users _(the string representation of version 4 UUIDs)._\n\nIf research and/or user feedback later indicates that additional functionality, such as versions 1,\n3, and 5 UUIDs, would add value, this proposal does not preclude these additions.\n\n## Use cases\n\nHow do folks in the community use RFC 4122 UUIDs?\n\n### Creating unique keys for database entries\n\n### Generating fake testing data\n\n### Writing to temporary files\n\n## FAQ\n\n### What are the advantages to uuid being in the standard library?\n\n- The `uuid` module is relied on by `\u003e 2,600,000` repos on GitHub (June 2019). Guaranteeing a\n  secure, consistent, well-maintained UUID implementation provides value to millions of developers.\n- The 12 kb `uuid` module is downloaded from npm `\u003e 62,000,000` times a month (June 2019); making\n  it available in the standard library eventually saves TBs of bandwidth globally. If we continue\n  to address user needs, such as `uuid`, with the standard library, bandwidth savings add up.\n\n### How unique are v4 UUIDs?\n\nIf you ignore the\n[challenges involved in random number generation](https://hackaday.com/2017/11/02/what-is-entropy-and-how-do-i-get-more-of-it/),\nthen v4 UUIDs are unique enough for all but the most stringent use cases. For example, the odds of\na collision among 3.3 quadrillion version 4 UUIDs (equivalent to generating a million UUIDs/second\nfor 104 years) is roughly one in a million (p = 0.000001).\n[Source](https://en.wikipedia.org/wiki/Universally_unique_identifier#Collisions).\n\nThat said, the quality of the random number generator is vital to uniqueness. Flawed RNG\nimplementations have led to\n[UUID collisions in real-world systems](https://github.com/bcoe/proposal-standard-library-uuid/issues/20).\nIt is for this reason that this spec mandates that any random numbers used come from a\n\"cryptographically secure\" source, thereby (hopefully) avoiding such issues.\n\n### Why call the export `randomUUID()` and not something like `uuidV4()`?\n\nAs pointed out\n[in the disucssion](https://github.com/tc39/proposal-uuid/issues/3#issuecomment-544173041) `v4`\nUUIDs have the maximum amount of entropy possible for a valid UUID as defined in [IETF RFC\n4122][rfc-4122].\n\nUUIDs defined in [IETF RFC 4122][rfc-4122] are 128 bit numbers that follow a specific byte layout.\nAll of them contain a \"version\" field comprising 4 bits and a \"variant\" field comprising 2 bits,\nmeaning that 6 out of 128 bits are reserved for meta information.\n\nSince `v4` UUIDs are defined to have all remaining 122 bits set to random values, there cannot be\nanother UUID version that would contain more randomness.\n\nWhile any name involving `v4` requires a rather deep understanding of the intricate meaning of the\nterm \"version\" in the context of the UUID spec, the term `randomUUID()` appears to be much more\ndescriptive for `v4` UUIDs.\n\n### Aren't v1 UUIDs better because they are guaranteed to be unique?\n\nAs an oversimplification, `v1` UUIDs consist of two parts: A high-precision `timestamp` and a\n`node` id. [IETF RFC 4122][rfc-4122] contains several requirements that are supposed to ensure that\nthe resulting `v1` UUIDs are unique.\n\n- The timestamp has 100 nanosecond resolution and implementations are\n  [required to throw an error or stall](https://tools.ietf.org/html/rfc4122#section-4.2.1.2) on\n  attempts to generate UUIDs at a rate higher than 10M/second on a single `node`. Realistically\n  that's only enforceable within a single thread/process on a single host. Enforcing this across\n  multiple processes / hosts requires non-trivial architectures that run counter to the\n  [main thesis the UUID spec](https://tools.ietf.org/html/rfc4122#section-2): _\"One of the main\n  reasons for using UUIDs is that no centralized authority is required to administer them\"._\n- The mechanism for generating `node` values preferred by the RFC is to use the host system's IEEE\n  802 MAC address. This made sense back when the RFC was authored and MAC addresses could\n  reasonably be expected to be unique, but this is arguably no longer the case, not with the\n  proliferation of virtual machines and containers where MAC addresses may not be unique\n  [_by design_](https://stackoverflow.com/a/42947044).\n\nSo in practice, modern implementations will generate a random 48 bit `node` value each time a\nprocess is started leaving a probability of 1 in 2\u003csup\u003e48\u003c/sup\u003e for collisions in the `node` part.\nIn the unlikely event of such a collision\n[it would take only 75 milliseconds](https://github.com/bcoe/proposal-standard-library-uuid/issues/15#issuecomment-522415349)\nfor a duplicate `v1` UUID to appear when generating UUIDs at a rate of 1M/second. So while also\nunlikely, [just like with `v4` UUIDs](#how-unique-are-v4-uuids) there is no practical guarantee\nthat `v1` UUIDs are unique.\n\n### Are there privacy concerns related to v1 UUIDs?\n\nIf implementations follow\n[the primary recommendations of RFC 4122](https://tools.ietf.org/html/rfc4122#section-4.1.6) then\n`v1` UUIDs would indeed leak the hardware MAC address of the machine where they are being created.\n[As discussed above](#but-arent-v1-uuids-better-because-they-are-guaranteed-to-be-unique) this\nwould most likely not be the case in modern JavaScript implementations where hardware MAC addresses\nare either unavailable (browser, serverless functions) or not necessarily unique\n([containers](https://stackoverflow.com/a/42947044)). However, there are\n[rumors that the presence of the MAC address lead to the arrest of the authors of the Melissa Virus](https://news.ycombinator.com/item?id=8575606)\nand according to the manual even\n[MySQL 8.0 still uses the hardware MAC address on some operating systems](https://dev.mysql.com/doc/refman/8.0/en/miscellaneous-functions.html#function_uuid).\n\nIn any case the exact creation time of any `v1` UUID will be contained within the UUID. This alone\ncan be a privacy or data protection concern for many use cases (e.g. leaking the creation timestamp\nof a user account) so it's yet another reason to be very careful when choosing to use `v1` UUIDs.\n\n### How do other languages/libraries deal with UUIDs?\n\nSome other languages/libraries use the term \"random\" to describe version 4 UUIDs as well\n([go](https://godoc.org/github.com/google/uuid#NewRandom),\n[Java](\u003chttps://docs.oracle.com/javase/10/docs/api/java/util/UUID.html#randomUUID()\u003e),\n[C++ Boost](https://www.boost.org/doc/libs/1_71_0/boost/uuid/random_generator.hpp)).\n\nApart from that, UUID adoption across other languages/libraries seems to be rather inconsistent:\n\n- [deno](https://github.com/denoland/deno/tree/master/std/uuid) added UUID to their standard\n  library, leaving out `v3`. The code for UUID creation is essentially copied from the\n  [`uuid` npm module](https://github.com/uuidjs/uuid), hence method naming follows the `vX` scheme.\n- [Java](https://docs.oracle.com/javase/10/docs/api/java/util/UUID.html) provides methods for\n  generating\n  `v3`([`UUID.nameUUIDFromBytes()`](\u003chttps://docs.oracle.com/javase/10/docs/api/java/util/UUID.html#nameUUIDFromBytes(byte%5B%5D)\u003e))\n  and `v4`\n  ([`UUID.randomUUID()`](\u003chttps://docs.oracle.com/javase/10/docs/api/java/util/UUID.html#randomUUID()\u003e))\n  UUIDs but not `v1` or `v5`. It would be interesting to investigate further as to why these\n  algorithms were chosen, given that on the one hand time-based UUIDs (`v1`) appear to have much\n  broader use than name-based (`v3`/`v5`) UUIDs and that on the other hand for name-based UUIDs the\n  [RFC already recommends `v5` over `v3`](https://tools.ietf.org/html/rfc4122#section-4.3).\n- [C++ Boost](https://www.boost.org/doc/libs/1_71_0/libs/uuid/doc/uuid.html#boost/uuid/name_generator.hpp)\n  defaults to `v5` over `v3` for name-based UUIDs but in its implementation anticipates that `v5`\n  (which uses SHA-1 for hashing) will be followed up by a newer name-based UUID version which will\n  use a different hashing algorithm (\"In anticipation of a new RFC for uuid arriving…\").\n- [Google's implementation for go](https://godoc.org/github.com/google/uuid#NewUUID) has chosen\n  `v1` to be the \"default\" export whose generator method is called `NewUUID()`, whereas the other\n  exposed methods have names closer to the abstraction we propose: `NewRandom()` for `v4`,\n  `NewMD5()` for `v3`, `NewSHA1()` for `v5`.\n- [Python](https://docs.python.org/3/library/uuid.html) provides methods for generating UUIDs named\n  after the version for all 4 versions (`uuid.uuid1()`, `uuid.uuid3()`, `uuid.uuid4()` and\n  `uuid.uuid5()`) plus a `UUID` class to represent UUIDs and transform them into various\n  representations.\n- [Rust](https://docs.rs/uuid/latest/uuid/) provides methods for generating UUIDs named after the\n  version for all 4 versions (`Uuid::new_v1()`, `Uuid::new_v3()`, `Uuid::new_v4()` and\n  `Uuid::new_v5()`) as static members of a `Uuid` class which is used to represent UUIDs and\n  transform them into various representations.\n\n## TODO\n\n- [x] Identify champion to advance addition (stage-1)\n- [x] Prose outlining the problem or need and general shape of the solution (stage-1)\n- [x] Illustrative examples of usage (stage-1)\n- [x] High-level API (stage-1)\n- [ ] Initial spec text (stage-2)\n- [ ] Babel plugin (stage-2)\n- [ ] Finalize and reviewer sign-off for spec text (stage-3)\n- [ ] Test262 acceptance tests (stage-4)\n- [ ] tc39/ecma262 pull request with integrated spec text (stage-4)\n- [ ] Reviewer sign-off (stage-4)\n\n## References\n\n- [IETF RFC 4122][rfc-4122]\n- [JavaScript Standard Library Proposal][standard-library-proposal]\n- [TIFU by using `Math.random()`][tifu]\n- [Cryptographically secure pseudorandom number generator][csprng]\n\n[rfc-4122]: https://tools.ietf.org/html/rfc4122\n[standard-library-proposal]: https://github.com/tc39/proposal-javascript-standard-library\n[tifu]: https://medium.com/@betable/tifu-by-using-math-random-f1c308c4fd9d\n[csprng]: https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-uuid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftc39%2Fproposal-uuid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftc39%2Fproposal-uuid/lists"}