docs: deprecated deep requiring of the different algorithm versions (#…

…361)

BREAKING CHANGE: 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.

README.md

@@ -17,6 +17,36 @@ Features:
 ⚠️⚠️⚠️ 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 (where bundlesize is no concern) just require the main
+package:
+
+```javascript
+const uuid = require('uuid');
+uuid.v4();
+```
+
 ## Quickstart - Node.js/CommonJS
 
 ```shell
@@ -102,8 +132,8 @@ tree-shaking for bundlers, like [rollup.js](https://rollupjs.org/guide/en/#tree-
 ([example](./examples/browser-webpack/)).
 
 ```javascript
-import { v4 as uuid } from 'uuid';
-uuid(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
+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

README_js.md

@@ -30,6 +30,36 @@ Features:
 ⚠️⚠️⚠️ 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 (where bundlesize is no concern) just require the main
+package:
+
+```javascript
+const uuid = require('uuid');
+uuid.v4();
+```
+
 ## Quickstart - Node.js/CommonJS
 
 ```shell
@@ -111,8 +141,8 @@ tree-shaking for bundlers, like [rollup.js](https://rollupjs.org/guide/en/#tree-
 ([example](./examples/browser-webpack/)).
 
 ```javascript
-import { v4 as uuid } from 'uuid';
-uuid(); // ⇨ '1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed'
+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

package.json

@@ -24,7 +24,11 @@
     "CONTRIBUTING.md",
     "LICENSE.md",
     "README.md",
-    "dist"
+    "dist",
+    "v1.js",
+    "v3.js",
+    "v4.js",
+    "v5.js"
   ],
   "devDependencies": {
     "@babel/cli": "7.8.3",
@@ -59,7 +63,8 @@
     "lint": "npm run eslint:check && npm run prettier:check",
     "eslint:check": "eslint src/ test/ examples/ *.js",
     "eslint:fix": "eslint --fix src/ test/ examples/ *.js",
-    "test": "BABEL_ENV=commonjs jest test/unit/",
+    "pretest": "npm run build",
+    "test": "BABEL_ENV=commonjs node --throw-deprecation node_modules/.bin/jest test/unit/",
     "pretest:browser": "npm run build && npm-run-all --parallel examples:**",
     "test:browser": "BABEL_ENV=commonjs jest --forceExit --verbose test/browser/${BROWSER:-}*",
     "prettier:check": "prettier --ignore-path .prettierignore --check '**/*.{js,jsx,json,md}'",

test/unit/deep-require-deprecation.test.js

@@ -0,0 +1,35 @@
+const assert = require('assert');
+
+describe('deprecate deep require', () => {
+  function assertDeprecation(doRequire) {
+    return () => {
+      const uuid = doRequire();
+      try {
+        uuid();
+        assert(false); // ensure this line is never reached
+      } catch (error) {
+        assert.strictEqual(error.name, 'DeprecationWarning');
+      }
+    };
+  }
+
+  test(
+    'v1',
+    assertDeprecation(() => require('../../v1')),
+  );
+
+  test(
+    'v3',
+    assertDeprecation(() => require('../../v3')),
+  );
+
+  test(
+    'v4',
+    assertDeprecation(() => require('../../v4')),
+  );
+
+  test(
+    'v5',
+    assertDeprecation(() => require('../../v5')),
+  );
+});

v1.js

@@ -0,0 +1,8 @@
+const util = require('util');
+
+const v1 = require('./dist/v1.js');
+
+module.exports = util.deprecate(
+  v1,
+  "Deep requiring like `const uuidv1 = require('uuid/v1');` is deprecated as of uuid@7.x. Please require the top-level module when using the Node.js CommonJS module or use ECMAScript Modules when bundling for the browser. See https://github.com/uuidjs/uuid/blob/master/README.md#upgrading-from-v3x-of-this-module for more information.",
+);

v3.js

@@ -0,0 +1,8 @@
+const util = require('util');
+
+const v3 = require('./dist/v3.js');
+
+module.exports = util.deprecate(
+  v3,
+  "Deep requiring like `const uuidv3 = require('uuid/v3');` is deprecated as of uuid@7.x. Please require the top-level module when using the Node.js CommonJS module or use ECMAScript Modules when bundling for the browser. See https://github.com/uuidjs/uuid/blob/master/README.md#upgrading-from-v3x-of-this-module for more information.",
+);

v4.js

@@ -0,0 +1,8 @@
+const util = require('util');
+
+const v4 = require('./dist/v4.js');
+
+module.exports = util.deprecate(
+  v4,
+  "Deep requiring like `const uuidv4 = require('uuid/v4');` is deprecated as of uuid@7.x. Please require the top-level module when using the Node.js CommonJS module or use ECMAScript Modules when bundling for the browser. See https://github.com/uuidjs/uuid/blob/master/README.md#upgrading-from-v3x-of-this-module for more information.",
+);

v5.js

@@ -0,0 +1,8 @@
+const util = require('util');
+
+const v5 = require('./dist/v5.js');
+
+module.exports = util.deprecate(
+  v5,
+  "Deep requiring like `const uuidv5 = require('uuid/v5');` is deprecated as of uuid@7.x. Please require the top-level module when using the Node.js CommonJS module or use ECMAScript Modules when bundling for the browser. See https://github.com/uuidjs/uuid/blob/master/README.md#upgrading-from-v5x-of-this-module for more information.",
+);