uuid 7.0.0-beta.0 → 7.0.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [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)
 
 ### Features

package/README.md

@@ -4,47 +4,20 @@
 
 # uuid [![Build Status](https://github.com/uuidjs/uuid/workflows/CI/badge.svg)](https://github.com/uuidjs/uuid/actions)
 
-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
-
-⚠️⚠️⚠️ 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();
-```
+**Upgrading from uuid\@3?** Your code is probably okay, but check out [Upgrading
+From uuid\@3](#upgrading-from-uuid3) for details.
 
 ## Quickstart - Node.js/CommonJS
 
@@ -52,92 +25,56 @@ uuidv4();
 npm install uuid
 ```
 
-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) - 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).
 
-Version 4 (random):
+### Create Version 4 (Random) UUIDs
 
 ```javascript
 import { v4 as uuidv4 } from 'uuid';
 uuidv4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
 ```
 
-Or generate UUIDs with other algorithms of your choice ...
-
-Version 1 (timestamp):
+### Create Version 1 (Timestamp) UUIDs
 
 ```javascript
 import { v1 as uuidv1 } from 'uuid';
 uuidv1(); // ⇨ '2c5ea4c0-4067-11e9-8b2d-1b9d6bcdbbfd'
 ```
 
-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'
-
-// ... 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):
+⚠️ If using a custom namespace **be sure to generate your own
+namespace UUID**. You can grab one [here](https://www.uuidgenerator.net/).
 
 ```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'
-```
-
-## 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
+uuidv3('Hello, World!', MY_NAMESPACE); // ⇨ 'e8b5a51d-11c8-3310-a6ab-367563f20686'
 ```
 
 ## API
@@ -153,7 +90,7 @@ uuidv4(options);
 uuidv4(options, buffer, offset);
 ```
 
-Generate and return a RFC4122 v4 UUID.
+Generate and return a RFC4122 version 4 UUID.
 
 - `options` - (Object) Optional uuid state to apply. Properties may include:
   - `random` - (Number[16]) Array of 16 numbers (0-255) to use in place of randomly generated values. Takes precedence over `options.rng`.
@@ -209,11 +146,7 @@ uuidv4(null, buffer, 16); // ⇨
   // ]
 ```
 
-### Version 1 (Timestamp + Node)
-
-⚠️⚠️⚠️ **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.** ⚠️⚠️⚠️
+### Version 1 (Timestamp)
 
 ```javascript
 import { v1 as uuidv1 } from 'uuid';
@@ -224,7 +157,7 @@ uuidv1(options);
 uuidv1(options, buffer, offset);
 ```
 
-Generate and return a RFC4122 v1 (timestamp-based) UUID.
+Generate and return a RFC4122 version 1 (timestamp) UUID.
 
 - `options` - (Object) Optional uuid state to apply. Properties may include:
   - `node` - (Array) Node id as Array of 6 bytes (per 4.1.6). Default: Randomly generated ID. See note 1.
@@ -273,18 +206,18 @@ uuidv1(null, arr, 16); // ⇨
   // ]
 ```
 
-### 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.
 
 - `name` - (String | Array[]) "name" to create UUID with
 - `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values
@@ -296,21 +229,23 @@ Returns `buffer`, if specified, otherwise the string form of the UUID
 Example:
 
 ```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.
 
 - `name` - (String | Array[]) "name" to create UUID with
 - `namespace` - (String | Array[]) "namespace" UUID either as a String or Array[16] of byte values
@@ -322,24 +257,58 @@ Returns `buffer`, if specified, otherwise the string form of the UUID
 Example:
 
 ```javascript
-uuidv5('hello world', MY_NAMESPACE); // ⇨ '9f282611-e0fd-5650-8953-89c8e342da0b'
+uuidv3('hello world', MY_NAMESPACE); // ⇨ '042ffd34-d989-321c-ad06-f60826172424'
 ```
 
 ## Command Line
 
-UUIDs can be generated from the command line with the `uuid` command.
+UUIDs can be generated from the command line using `uuid`.
 
 ```shell
 $ uuid
 ddeb27fb-d9a0-4624-be4d-4615062daed4
+```
+
+The default is to generate version 4 UUIDS, however the other versions are supported. Type `uuid --help` for details:
 
-$ uuid v1
-02d37060-d446-11e7-a9fa-7bdae751ebe1
 ```
+$ uuid --help
+
+Usage:
+  uuid
+  uuid v1
+  uuid v3 <name> <namespace uuid>
+  uuid v4
+  uuid v5 <name> <namespace uuid>
+  uuid --help
+
+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.
 
-Type `uuid --help` for usage details
+To run the examples you must first create a dist build of this library in the module root:
 
-## UMD Build
+```
+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
 CDNs:
@@ -365,5 +334,50 @@ Available bundles:
 - https://unpkg.com/uuid@latest/dist/umd/
 - https://cdn.jsdelivr.net/npm/uuid@latest/dist/umd/
 
+## 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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uuid",
-  "version": "7.0.0-beta.0",
+  "version": "7.0.0",
   "description": "RFC4122 (v1, v4, and v5) UUIDs",
   "commitlint": {
     "extends": [
@@ -31,30 +31,30 @@
     "v5.js"
   ],
   "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",
     "@commitlint/config-conventional": "8.3.4",
     "babel-eslint": "10.0.3",
     "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",
     "esm": "3.2.25",
     "http-server": "0.12.1",
     "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"
   },
   "scripts": {
     "examples:browser-webpack:build": "cd examples/browser-webpack && npm install && npm run build",