From c0bdf15e417639b1aeb0b247b2fb11f7a0a26b23 Mon Sep 17 00:00:00 2001 From: Christoph Tavan Date: Thu, 13 Feb 2020 14:42:48 +0100 Subject: [PATCH] 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 | 34 +++++++++++++++++++-- README_js.md | 34 +++++++++++++++++++-- package.json | 9 ++++-- test/unit/deep-require-deprecation.test.js | 35 ++++++++++++++++++++++ v1.js | 8 +++++ v3.js | 8 +++++ v4.js | 8 +++++ v5.js | 8 +++++ 8 files changed, 138 insertions(+), 6 deletions(-) create mode 100644 test/unit/deep-require-deprecation.test.js create mode 100644 v1.js create mode 100644 v3.js create mode 100644 v4.js create mode 100644 v5.js diff --git a/README.md b/README.md index b0b09880..7e0b66b7 100644 --- a/README.md +++ b/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 diff --git a/README_js.md b/README_js.md index deae90b3..10866bd1 100644 --- a/README_js.md +++ b/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 diff --git a/package.json b/package.json index 33a3a582..94400777 100644 --- a/package.json +++ b/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}'", diff --git a/test/unit/deep-require-deprecation.test.js b/test/unit/deep-require-deprecation.test.js new file mode 100644 index 00000000..32ac626a --- /dev/null +++ b/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')), + ); +}); diff --git a/v1.js b/v1.js new file mode 100644 index 00000000..fc0f5f87 --- /dev/null +++ b/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.", +); diff --git a/v3.js b/v3.js new file mode 100644 index 00000000..6e5ba606 --- /dev/null +++ b/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.", +); diff --git a/v4.js b/v4.js new file mode 100644 index 00000000..45f8c2ff --- /dev/null +++ b/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.", +); diff --git a/v5.js b/v5.js new file mode 100644 index 00000000..db1f831b --- /dev/null +++ b/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.", +);