Comparing version 7.0.0-beta.0 to 7.0.0
@@ -5,2 +5,38 @@ # Changelog | ||
## [7.0.0](https://github.com/uuidjs/uuid/compare/v3.4.0...v7.0.0) (2020-02-24) | ||
### ⚠ BREAKING CHANGES | ||
- The default export, which used to be the v4() method | ||
but which was already discouraged in v3.x of this library, has been | ||
removed. | ||
- Explicitly note that deep imports of the different uuid | ||
version functions are deprecated and no longer encouraged and that | ||
ECMAScript module named imports should be used instead. | ||
Emit a deprecation warning for people who deep-require the different | ||
algorithm variants. | ||
- Remove builtin support for insecure random number | ||
generators in the browser. Users who want that will have to supply their | ||
own random number generator function. | ||
- Remove support for generating v3 and v5 UUIDs in | ||
Node.js<4.x | ||
- Convert code base to ECMAScript Modules (ESM) and | ||
release CommonJS build for node and ESM build for browser bundlers. | ||
### Features | ||
- add UMD build to npm package ([#357](https://github.com/uuidjs/uuid/issues/357)) ([4e75adf](https://github.com/uuidjs/uuid/commit/4e75adf435196f28e3fbbe0185d654b5ded7ca2c)), closes [#345](https://github.com/uuidjs/uuid/issues/345) | ||
- add various es module and CommonJS examples ([b238510](https://github.com/uuidjs/uuid/commit/b238510bf352463521f74bab175a3af9b7a42555)) | ||
- ensure that docs are up-to-date in CI ([ee5e77d](https://github.com/uuidjs/uuid/commit/ee5e77db547474f5a8f23d6c857a6d399209986b)) | ||
- hybrid CommonJS & ECMAScript modules build ([a3f078f](https://github.com/uuidjs/uuid/commit/a3f078faa0baff69ab41aed08e041f8f9c8993d0)) | ||
- remove insecure fallback random number generator ([3a5842b](https://github.com/uuidjs/uuid/commit/3a5842b141a6e5de0ae338f391661e6b84b167c9)), closes [#173](https://github.com/uuidjs/uuid/issues/173) | ||
- remove support for pre Node.js v4 Buffer API ([#356](https://github.com/uuidjs/uuid/issues/356)) ([b59b5c5](https://github.com/uuidjs/uuid/commit/b59b5c5ecad271c5453f1a156f011671f6d35627)) | ||
- rename repository to github:uuidjs/uuid ([#351](https://github.com/uuidjs/uuid/issues/351)) ([c37a518](https://github.com/uuidjs/uuid/commit/c37a518e367ac4b6d0aa62dba1bc6ce9e85020f7)), closes [#338](https://github.com/uuidjs/uuid/issues/338) | ||
### Bug Fixes | ||
- add deep-require proxies for local testing and adjust tests ([#365](https://github.com/uuidjs/uuid/issues/365)) ([7fedc79](https://github.com/uuidjs/uuid/commit/7fedc79ac8fda4bfd1c566c7f05ef4ac13b2db48)) | ||
- add note about removal of default export ([#372](https://github.com/uuidjs/uuid/issues/372)) ([12749b7](https://github.com/uuidjs/uuid/commit/12749b700eb49db8a9759fd306d8be05dbfbd58c)), closes [#370](https://github.com/uuidjs/uuid/issues/370) | ||
- deprecated deep requiring of the different algorithm versions ([#361](https://github.com/uuidjs/uuid/issues/361)) ([c0bdf15](https://github.com/uuidjs/uuid/commit/c0bdf15e417639b1aeb0b247b2fb11f7a0a26b23)) | ||
## [3.4.0](https://github.com/uuidjs/uuid/compare/v3.3.3...v3.4.0) (2020-01-16) | ||
@@ -7,0 +43,0 @@ |
{ | ||
"name": "uuid", | ||
"version": "7.0.0-beta.0", | ||
"version": "7.0.0", | ||
"description": "RFC4122 (v1, v4, and v5) UUIDs", | ||
@@ -34,5 +34,5 @@ "commitlint": { | ||
"devDependencies": { | ||
"@babel/cli": "7.8.3", | ||
"@babel/core": "7.8.3", | ||
"@babel/preset-env": "7.8.3", | ||
"@babel/cli": "7.8.4", | ||
"@babel/core": "7.8.4", | ||
"@babel/preset-env": "7.8.4", | ||
"@commitlint/cli": "8.3.5", | ||
@@ -42,6 +42,6 @@ "@commitlint/config-conventional": "8.3.4", | ||
"babel-plugin-add-module-exports": "1.0.2", | ||
"browserstack-local": "1.4.4", | ||
"browserstack-local": "1.4.5", | ||
"bundlewatch": "0.2.5", | ||
"eslint": "6.8.0", | ||
"eslint-config-prettier": "6.9.0", | ||
"eslint-config-prettier": "6.10.0", | ||
"eslint-plugin-prettier": "3.1.2", | ||
@@ -51,11 +51,11 @@ "esm": "3.2.25", | ||
"husky": "3.0.9", | ||
"jest": "24.9.0", | ||
"lint-staged": "10.0.1", | ||
"jest": "25.1.0", | ||
"lint-staged": "10.0.7", | ||
"npm-run-all": "4.1.5", | ||
"prettier": "1.19.1", | ||
"rollup": "1.30.0", | ||
"rollup": "1.31.1", | ||
"rollup-plugin-terser": "5.2.0", | ||
"runmd": "1.3.2", | ||
"selenium-webdriver": "3.6.0", | ||
"standard-version": "7.0.1" | ||
"standard-version": "7.1.0" | ||
}, | ||
@@ -62,0 +62,0 @@ "scripts": { |
268
README.md
@@ -7,44 +7,17 @@ <!-- | ||
Simple, fast generation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDs. | ||
For the creation of [RFC4122](http://www.ietf.org/rfc/rfc4122.txt) UUIDs | ||
Features: | ||
- **Complete** - Support for RFC4122 version 1, 3, 4, and 5 UUIDs | ||
- **Cross-platform** - Support for ... | ||
- CommonJS, [ECMAScript Modules](#ecmascript-modules) and UMD builds | ||
- Node 8, 10, 12 | ||
- Chrome, Safari, Firefox, Edge, IE 11 browsers | ||
- Webpack and rollup.js module bundlers | ||
- **Secure** - Cryptographically-strong random values | ||
- **Small** - Zero-dependency, small footprint, plays nice with "tree shaking" packagers | ||
- **CLI** - Includes the [`uuid` command line](#command-line) utility | ||
- Support for version 1, 3, 4 and 5 UUIDs | ||
- Cross-platform: CommonJS build for Node.js and [ECMAScript Modules](#ecmascript-modules) for the | ||
browser. | ||
- Uses cryptographically-strong random number APIs | ||
- Zero-dependency, small footprint | ||
**Upgrading from uuid\@3?** Your code is probably okay, but check out [Upgrading | ||
From uuid\@3](#upgrading-from-uuid3) for details. | ||
⚠️⚠️⚠️ This is the README of the upcoming major version of this library. You can still [access the README | ||
of the current stable version](https://github.com/uuidjs/uuid/blob/v3.4.0/README.md). ⚠️⚠️⚠️ | ||
## Upgrading from v3.x of this Module | ||
In v3.x of this library we were promoting the use of deep requires to reduce bundlesize for browser | ||
builds: | ||
```javascript | ||
const uuidv4 = require('uuid/v4'); | ||
uuidv4(); | ||
``` | ||
As of v7.x this library has been converted to ECMAScript Modules and deep requires are now | ||
deprecated and may be removed in a future major version of this library. | ||
Since all modern bundlers like rollup or Webpack support tree-shaking for ECMAScript Modules out of | ||
the box we now encourage you to use modern `import` syntax instead, see [ECMAScript Modules / | ||
ESM](#ecmascript-modules--esm): | ||
```javascript | ||
import { v4 as uuidv4 } from 'uuid'; | ||
uuidv4(); | ||
``` | ||
For use as CommonJS module with Node.js you can use: | ||
```javascript | ||
const { v4: uuidv4 } = require('uuid'); | ||
uuidv4(); | ||
``` | ||
## Quickstart - Node.js/CommonJS | ||
@@ -56,6 +29,14 @@ | ||
Then generate a random UUID (v4 algorithm), which is almost always what you want ... | ||
Once installed, decide which type of UUID you need. RFC4122 provides for four | ||
versions, all of which are supported here. In order of popularity, they are: | ||
Version 4 (random): | ||
- Version 4 (random) - Created from cryptographically-strong random values | ||
- Version 1 (timestamp) - Created from the system clock (plus random values) | ||
- Version 5 (namespace, SHA-1) - Created from user-supplied name and namespace strings | ||
- Version 3 (namespace, MD5) - Like version 5, above, but with a poorer hash algorithm | ||
**Unsure which one to use?** Use version 4 (random) unless you have a specific need for one of the other versions. See also [this FAQ](https://github.com/tc39/proposal-uuid#faq). | ||
### Create Version 4 (Random) UUIDs | ||
```javascript | ||
@@ -66,6 +47,4 @@ import { v4 as uuidv4 } from 'uuid'; | ||
Or generate UUIDs with other algorithms of your choice ... | ||
### Create Version 1 (Timestamp) UUIDs | ||
Version 1 (timestamp): | ||
```javascript | ||
@@ -76,72 +55,30 @@ import { v1 as uuidv1 } from 'uuid'; | ||
Version 3 (namespace): | ||
### Create Version 3 or Version 5 (Namespace) UUIDs | ||
```javascript | ||
import { v3 as uuidv3 } from 'uuid'; | ||
⚠️ Version 3 and Version 5 UUIDs are basically the same, differing | ||
only in the underlying hash algorithm. Note that per the RFC, "_If backward | ||
compatibility is not an issue, SHA-1 [Version 5] is preferred_." | ||
// ... using predefined DNS namespace (for domain names) | ||
uuidv3('hello.example.com', uuidv3.DNS); // ⇨ '9125a8dc-52ee-365b-a5aa-81b0b3681cf6' | ||
⚠️ If using a custom namespace **be sure to generate your own | ||
namespace UUID**. You can grab one [here](https://www.uuidgenerator.net/). | ||
// ... using predefined URL namespace (for, well, URLs) | ||
uuidv3('http://example.com/hello', uuidv3.URL); // ⇨ 'c6235813-3ba4-3801-ae84-e0a6ebb7d138' | ||
// ... using a custom namespace | ||
// | ||
// Note: Custom namespaces should be a UUID string specific to your application! | ||
// E.g. the one here was generated using this modules `uuid` CLI. | ||
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; | ||
uuidv3('Hello, World!', MY_NAMESPACE); // ⇨ 'e8b5a51d-11c8-3310-a6ab-367563f20686' | ||
``` | ||
Version 5 (namespace): | ||
```javascript | ||
import { v5 as uuidv5 } from 'uuid'; | ||
import { v5 as uuidv5 } from 'uuid'; // For version 5 | ||
import { v3 as uuidv3 } from 'uuid'; // For version 3 | ||
// ... using predefined DNS namespace (for domain names) | ||
// Using predefined DNS namespace (for domain names) | ||
uuidv5('hello.example.com', uuidv5.DNS); // ⇨ 'fdda765f-fc57-5604-a269-52a7df8164ec' | ||
uuidv3('hello.example.com', uuidv3.DNS); // ⇨ '9125a8dc-52ee-365b-a5aa-81b0b3681cf6' | ||
// ... using predefined URL namespace (for, well, URLs) | ||
// Using predefined URL namespace (for URLs) | ||
uuidv5('http://example.com/hello', uuidv5.URL); // ⇨ '3bbcee75-cecc-5b56-8031-b6641c1ed1f1' | ||
uuidv3('http://example.com/hello', uuidv3.URL); // ⇨ 'c6235813-3ba4-3801-ae84-e0a6ebb7d138' | ||
// ... using a custom namespace | ||
// | ||
// Note: Custom namespaces should be a UUID string specific to your application! | ||
// E.g. the one here was generated using this modules `uuid` CLI. | ||
// Using a custom namespace (See note, above, about generating your own | ||
// namespace UUID) | ||
const MY_NAMESPACE = '1b671a64-40d5-491e-99b0-da01ff1f3341'; | ||
uuidv5('Hello, World!', MY_NAMESPACE); // ⇨ '630eb68f-e0fa-5ecc-887a-7c7a62614681' | ||
uuidv3('Hello, World!', MY_NAMESPACE); // ⇨ 'e8b5a51d-11c8-3310-a6ab-367563f20686' | ||
``` | ||
## Supported Platforms | ||
- Node.js: All LTS, i.e. 8.x, 10.x, 12.x | ||
- Browsers (with bundlers like webpack/rollup): | ||
- Chrome: >= 49 | ||
- Safari: >= 10 | ||
- Firefox: >= 44 | ||
- Edge: >= 15 | ||
- IE: 11 | ||
## ECMAScript Modules / ESM | ||
For usage in the browser `uuid` provides support for [ECMAScript | ||
Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) that enable | ||
tree-shaking for bundlers, like [rollup.js](https://rollupjs.org/guide/en/#tree-shaking) | ||
([example](./examples/browser-rollup/)) and [webpack](https://webpack.js.org/guides/tree-shaking/) | ||
([example](./examples/browser-webpack/)). | ||
```javascript | ||
import { v4 as uuidv4 } from 'uuid'; | ||
uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed' | ||
``` | ||
There is experimental native ESM support for [the browser](./examples/browser-esmodules/) but it | ||
should not be considered ready for production use and may change or disappear in future releases. | ||
To run the examples you must first create a dist build of this library in the module root: | ||
``` | ||
npm run build | ||
``` | ||
## API | ||
@@ -160,3 +97,3 @@ | ||
Generate and return a RFC4122 v4 UUID. | ||
Generate and return a RFC4122 version 4 UUID. | ||
@@ -217,8 +154,4 @@ - `options` - (Object) Optional uuid state to apply. Properties may include: | ||
### Version 1 (Timestamp + Node) | ||
### Version 1 (Timestamp) | ||
⚠️⚠️⚠️ **Please make sure to check whether you really need the timestamp properties of Version 1 UUIDs | ||
before using them. In many cases, Version 4 random UUIDs are the better choice. [This | ||
FAQ](https://github.com/tc39/proposal-uuid#faq) covers more details.** ⚠️⚠️⚠️ | ||
```javascript | ||
@@ -233,3 +166,3 @@ import { v1 as uuidv1 } from 'uuid'; | ||
Generate and return a RFC4122 v1 (timestamp-based) UUID. | ||
Generate and return a RFC4122 version 1 (timestamp) UUID. | ||
@@ -283,14 +216,14 @@ - `options` - (Object) Optional uuid state to apply. Properties may include: | ||
### Version 3 (Namespace) | ||
### Version 5 (Namespace) | ||
```javascript | ||
import { v3 as uuidv3 } from 'uuid'; | ||
import { v5 as uuidv5 } from 'uuid'; | ||
// Incantations | ||
uuidv3(name, namespace); | ||
uuidv3(name, namespace, buffer); | ||
uuidv3(name, namespace, buffer, offset); | ||
uuidv5(name, namespace); | ||
uuidv5(name, namespace, buffer); | ||
uuidv5(name, namespace, buffer, offset); | ||
``` | ||
Generate and return a RFC4122 v3 UUID. | ||
Generate and return a RFC4122 version 5 UUID. | ||
@@ -307,17 +240,19 @@ - `name` - (String | Array[]) "name" to create UUID with | ||
```javascript | ||
uuidv3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f60826172424' | ||
uuidv5('hello world', MY_NAMESPACE); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b' | ||
``` | ||
### Version 5 (Namespace) | ||
### Version 3 (Namespace) | ||
⚠️ Note: Per the RFC, "_If backward compatibility is not an issue, SHA-1 [Version 5] is preferred_." | ||
```javascript | ||
import { v5 as uuidv5 } from 'uuid'; | ||
import { v3 as uuidv3 } from 'uuid'; | ||
// Incantations | ||
uuidv5(name, namespace); | ||
uuidv5(name, namespace, buffer); | ||
uuidv5(name, namespace, buffer, offset); | ||
uuidv3(name, namespace); | ||
uuidv3(name, namespace, buffer); | ||
uuidv3(name, namespace, buffer, offset); | ||
``` | ||
Generate and return a RFC4122 v5 UUID. | ||
Generate and return a RFC4122 version 3 UUID. | ||
@@ -334,3 +269,3 @@ - `name` - (String | Array[]) "name" to create UUID with | ||
```javascript | ||
uuidv5('hello world', MY_NAMESPACE); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b' | ||
uuidv3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f60826172424' | ||
``` | ||
@@ -340,3 +275,3 @@ | ||
UUIDs can be generated from the command line with the `uuid` command. | ||
UUIDs can be generated from the command line using `uuid`. | ||
@@ -346,11 +281,45 @@ ```shell | ||
ddeb27fb-d9a0-4624-be4d-4615062daed4 | ||
``` | ||
$ uuid v1 | ||
02d37060-d446-11e7-a9fa-7bdae751ebe1 | ||
The default is to generate version 4 UUIDS, however the other versions are supported. Type `uuid --help` for details: | ||
``` | ||
$ uuid --help | ||
Type `uuid --help` for usage details | ||
Usage: | ||
uuid | ||
uuid v1 | ||
uuid v3 <name> <namespace uuid> | ||
uuid v4 | ||
uuid v5 <name> <namespace uuid> | ||
uuid --help | ||
## UMD Build | ||
Note: <namespace uuid> may be "URL" or "DNS" to use the corresponding UUIDs | ||
defined by RFC4122 | ||
``` | ||
## ECMAScript Modules | ||
For usage in the browser `uuid` provides support for [ECMAScript | ||
Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) that enable | ||
tree-shaking for bundlers, like [rollup.js](https://rollupjs.org/guide/en/#tree-shaking) | ||
([example](./examples/browser-rollup/)) and [webpack](https://webpack.js.org/guides/tree-shaking/) | ||
([example](./examples/browser-webpack/)). | ||
```javascript | ||
import { v4 as uuidv4 } from 'uuid'; | ||
uuidv4(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed' | ||
``` | ||
There is experimental native ESM support for [the browser](./examples/browser-esmodules/) but it | ||
should not be considered ready for production use and may change or disappear in future releases. | ||
To run the examples you must first create a dist build of this library in the module root: | ||
``` | ||
npm run build | ||
``` | ||
## UMD Builds | ||
If you want to load a minified UMD build directly in the browser you can use one of the popular npm | ||
@@ -380,3 +349,48 @@ CDNs: | ||
## Upgrading From uuid\@3 | ||
"_Wait... what happened to uuid\@4 - uuid\@6?!?_" | ||
In order to avoid confusion with RFC [version 4](#version-4-random) and [version | ||
5](#version-5-namespace) UUIDs, and a possible [version | ||
6](http://gh.peabody.io/uuidv6/), releases 4 thru 6 of this module have been | ||
skipped. Hence, how we're now at uuid\@7. | ||
### Deep Requires Now Deprecated | ||
uuid\@3 encouraged the use of deep requires to minimize the bundle size of | ||
browser builds: | ||
```javascript | ||
const uuidv4 = require('uuid/v4'); // <== NOW DEPRECATED! | ||
uuidv4(); | ||
``` | ||
As of uuid\@7 this library now provides ECMAScript modules builds, which allow | ||
packagers like Webpack and Rollup to do "tree-shaking" to remove dead code. | ||
Instead, use the `import` syntax: | ||
```javascript | ||
import { v4 as uuidv4 } from 'uuid'; | ||
uuidv4(); | ||
``` | ||
... or for CommonJS: | ||
```javascript | ||
const { v4: uuidv4 } = require('uuid'); | ||
uuidv4(); | ||
``` | ||
### Default Export Removed | ||
uuid\@3 was exporting the Version 4 UUID method as a default export: | ||
```javascript | ||
const uuid = require('uuid'); // <== REMOVED! | ||
``` | ||
This usage pattern was already discouraged in uuid\@3 and has been removed in uuid\@7. | ||
---- | ||
Markdown generated from [README_js.md](README_js.md) by [![RunMD Logo](http://i.imgur.com/h0FVyzU.png)](https://github.com/broofa/runmd) |
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
72408
0
383
0