feat: native Node.js ES Modules (wrapper approach)

.github/workflows/ci.yml

@@ -38,3 +38,5 @@ jobs:
       if: matrix.node-version == '12.x'
       env:
         BUNDLEWATCH_GITHUB_TOKEN: ${{ secrets.BUNDLEWATCH_GITHUB_TOKEN }}
+    - run: npm run test:node
+      if: matrix.node-version == '12.x' || matrix.node-version == '14.x'

.local/wrapper.mjs

@@ -0,0 +1 @@
+../wrapper.mjs

README.md

@@ -297,20 +297,18 @@ 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/)).
+This library comes with [ECMAScript
+Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) support for Node.js
+versions that support it ([example](./examples/node-esmodules/)) as well as 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/)) (targeting both, Node.js and browser environments).
 
 ```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:
 
 ```

README_js.md

@@ -287,20 +287,18 @@ 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/)).
+This library comes with [ECMAScript
+Modules](https://www.ecma-international.org/ecma-262/6.0/#sec-modules) (ESM) support for Node.js
+versions that support it ([example](./examples/node-esmodules/)) as well as 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/)) (targeting both, Node.js and browser environments).
 
 ```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:
 
 ```

examples/node-esmodules/README.md

@@ -0,0 +1,6 @@
+# uuid example Node.js ESModules
+
+```
+npm install
+npm test
+```

examples/node-esmodules/example.mjs

@@ -0,0 +1,43 @@
+import { v1 as uuidv1, v4 as uuidv4, v3 as uuidv3, v5 as uuidv5 } from 'uuid';
+import * as uuid from 'uuid';
+
+console.log('uuidv1()', uuidv1());
+
+console.log('uuidv4()', uuidv4());
+
+// ... using predefined DNS namespace (for domain names)
+console.log('uuidv3() DNS', uuidv3('hello.example.com', uuidv3.DNS));
+
+// ... using predefined URL namespace (for, well, URLs)
+console.log('uuidv3() URL', uuidv3('http://example.com/hello', uuidv3.URL));
+
+// ... 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 = '55238d15-c926-4598-b49d-cf4e913ba13c';
+console.log('uuidv3() MY_NAMESPACE', uuidv3('Hello, World!', MY_NAMESPACE));
+
+// ... using predefined DNS namespace (for domain names)
+console.log('uuidv5() DNS', uuidv5('hello.example.com', uuidv5.DNS));
+
+// ... using predefined URL namespace (for, well, URLs)
+console.log('uuidv5() URL', uuidv5('http://example.com/hello', uuidv5.URL));
+
+// ... 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';
+console.log('uuidv5() MY_NAMESPACE', uuidv5('Hello, World!', MY_NAMESPACE));
+
+console.log('Same with default export');
+
+console.log('uuid.v1()', uuid.v1());
+console.log('uuid.v4()', uuid.v4());
+console.log('uuid.v3() DNS', uuid.v3('hello.example.com', uuid.v3.DNS));
+console.log('uuid.v3() URL', uuid.v3('http://example.com/hello', uuid.v3.URL));
+console.log('uuid.v3() MY_NAMESPACE', uuid.v3('Hello, World!', MY_NAMESPACE));
+console.log('uuid.v5() DNS', uuid.v5('hello.example.com', uuid.v5.DNS));
+console.log('uuid.v5() URL', uuid.v5('http://example.com/hello', uuid.v5.URL));
+console.log('uuid.v5() MY_NAMESPACE', uuid.v5('Hello, World!', MY_NAMESPACE));

examples/node-esmodules/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "uuid-example-node-esmodules",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "test": "node --experimental-modules example.mjs"
+  },
+  "dependencies": {
+    "uuid": "file:../../.local"
+  }
+}

package.json

@@ -14,10 +14,14 @@
   ],
   "license": "MIT",
   "bin": {
-    "uuid": "dist/bin/uuid"
+    "uuid": "./dist/bin/uuid"
   },
   "sideEffects": false,
   "main": "./dist/index.js",
+  "exports": {
+    "require": "./dist/index.js",
+    "import": "./wrapper.mjs"
+  },
   "module": "./dist/esm-node/index.js",
   "browser": {
     "./dist/md5.js": "./dist/md5-browser.js",
@@ -35,7 +39,8 @@
     "v1.js",
     "v3.js",
     "v4.js",
-    "v5.js"
+    "v5.js",
+    "wrapper.mjs"
   ],
   "devDependencies": {
     "@babel/cli": "7.8.4",
@@ -67,16 +72,19 @@
     "standard-version": "7.1.0"
   },
   "scripts": {
-    "examples:browser-webpack:build": "cd examples/browser-webpack && npm install && npm run build",
-    "examples:browser-rollup:build": "cd examples/browser-rollup && npm install && npm run build",
-    "examples:browser-esmodules:build": "cd examples/browser-esmodules && npm install && npm run build",
+    "examples:browser:webpack:build": "cd examples/browser-webpack && npm install && npm run build",
+    "examples:browser:rollup:build": "cd examples/browser-rollup && npm install && npm run build",
+    "examples:node:commonjs:test": "cd examples/node-commonjs && npm install && npm test",
+    "examples:node:esmodules:test": "cd examples/node-esmodules && npm install && npm test",
     "lint": "npm run eslint:check && npm run prettier:check",
     "eslint:check": "eslint src/ test/ examples/ *.js",
     "eslint:fix": "eslint --fix src/ test/ examples/ *.js",
     "pretest": "[ -n $CI ] || 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:**",
+    "pretest:browser": "npm run build && npm-run-all --parallel examples:browser:**",
     "test:browser": "wdio run ./wdio.conf.js",
+    "pretest:node": "npm run build",
+    "test:node": "npm-run-all --parallel examples:node:**",
     "prettier:check": "prettier --ignore-path .prettierignore --check '**/*.{js,jsx,json,md}'",
     "prettier:fix": "prettier --ignore-path .prettierignore --write '**/*.{js,jsx,json,md}'",
     "bundlewatch": "npm run pretest:browser && bundlewatch --config bundlewatch.config.json",

wrapper.mjs

@@ -0,0 +1,5 @@
+import uuid from './dist/index.js';
+export const v1 = uuid.v1;
+export const v3 = uuid.v3;
+export const v4 = uuid.v4;
+export const v5 = uuid.v5;