@std/esm - npm Package Compare versions

Comparing version 0.13.0 to 0.14.0

package.json

 {
   "name": "@std/esm",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Enable ES modules in Node today!",
@@ -5,0 +5,0 @@ "keywords": "commonjs, ecmascript, export, import, modules, node, require",

README.md

@@ -6,3 +6,4 @@ # @std/esm
 
-:book: See the [release post](https://medium.com/web-on-the-edge/es-modules-in-node-today-32cff914e4b)
+See the release [post](https://medium.com/web-on-the-edge/es-modules-in-node-today-32cff914e4b)
+:book: and [video](https://www.youtube.com/watch?v=60S1PFndbn0) :movie_camera:
 for all the details.
@@ -23,14 +24,14 @@
 
-     By default, `@std/esm` **only** processes files of packages that opt-in
-     with a `@std/esm` options object or `@std/esm` as a dependency, dev
-     dependency, or peer dependency in their package.json. However, you can
-     enable processing **all** files with specific options by passing an options
-     object as the second argument or passing `true` to use the options from
-     your package.json.
+By default, `@std/esm` **only** processes files of packages that opt-in
+with a `@std/esm` options object or `@std/esm` as a dependency, dev
+dependency, or peer dependency in their package.json. However, you can
+enable processing **all** files with specific options by passing an options
+object as the second argument or passing `true` to use the options from
+your package.json.
 
-     ```js
-     require = require("@std/esm")(module, optionsOrTrue)
-     ```
+```js
+require = require("@std/esm")(module, options)
+```
 
-Enable ESM in the Node CLI by loading `@std/esm` with the [`-r` option](https://nodejs.org/api/cli.html#cli_r_require_module):
+Enable ESM in the Node CLI with the [`-r` option](https://nodejs.org/api/cli.html#cli_r_require_module):
 
@@ -41,5 +42,11 @@ ```shell
 
-Enable ESM in the Node REPL by loading `@std/esm` upon entering:
+Enable ESM in the Node REPL:
 
 ```shell
+node -r @std/esm
+```
+
+Or upon entering:
+
+```shell
 $ node
@@ -84,4 +91,7 @@ > require("@std/esm")
 
-*Note: All options are **off** by default and may be specified as either an object or ESM mode string.*
+Commonly used options may be specified in shorthand form:
 
+* `"@std/esm":"js"` is shorthand for `"@std/esm":{"esm":"js"}`
+* `"@std/esm":"cjs"` is shorthand for `"@std/esm":{"cjs":true,"esm":"js"}`
+
 <table>
@@ -108,9 +118,3 @@ <tr>
   <td>
-    <p>A boolean for CJS features in ESM:</p>
-    <ul>
-    <li><code>__dirname</code> and <code>__filename</code></li>
-    <li><code>require</code> in ESM and loading ESM with <code>require</code></li>
-    <li><a href="https://ponyfoo.com/articles/es6-modules-in-depth#importing-named-exports">Importing named exports</a> of CJS modules</li>
-    <li><a href="http://stackoverflow.com/questions/28955047/why-does-a-module-level-return-statement-work-in-node-js/#28955050">Top-level <code>return</code></a></li>
-    </ul>
+    <p>A boolean to <a href="#contd">unlock</a> CJS features in ESM.</p>
   </td>
@@ -120,3 +124,5 @@ </tr>
   <td valign="top"><code>"await":</code></td>
-  <td><p>A boolean for top-level <code>await</code> in the main ES module.</p></td>
+  <td>
+    <p>A boolean to support top-level <code>await</code> in the main ES module.</p>
+  </td>
 </tr>
@@ -126,3 +132,3 @@ <tr>
   <td>
-    <p>A boolean for gzipped module support <i>(i.e. <code>.js.gz</code>, <code>.mjs.gz</code>).</i></p>
+    <p>A boolean to support gzipped module <i>(i.e. <code>.js.gz</code>, <code>.mjs.gz</code>).</i></p>
     <p><i>Note: Don’t forget the webpack <a href="https://webpack.js.org/loaders/gzip-loader/">gzip-loader</a>.</i></p>
@@ -139,2 +145,66 @@ </td>
 
+Cont’d
+---
+
+The `"cjs"` option may also be specified as an object.
+
+<table>
+<tr>
+  <td colspan="2">
+    <pre><code>{
+  "@std/esm": {
+    "cjs": {</code></pre>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"cache":</code></td>
+  <td>
+    <p>A boolean for storing ES modules in <code>require.cache</code>.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"extensions":</code></td>
+  <td>
+    <p>A boolean for respecting <code>require.extensions</code> in ES modules.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"interop":</code></td>
+  <td>
+    <p>A boolean for <code>__esModule</code> interoperability.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"namedExports":</code></td>
+  <td>
+    <p>A boolean to support <a href="https://ponyfoo.com/articles/es6-modules-in-depth#importing-named-exports">importing named exports</a> of CJS modules.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"paths":</code></td>
+  <td>
+    <p>A boolean for following CJS <a href="https://github.com/nodejs/node-eps/blob/master/002-es-modules.md#432-removal-of-non-local-dependencies">path rules</a> in ES modules.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"topLevelReturn":</code></td>
+  <td>
+    <p>A boolean to support <a href="http://stackoverflow.com/questions/28955047/why-does-a-module-level-return-statement-work-in-node-js/#28955050">top-level <code>return</code></a>.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"vars":</code></td>
+  <td>
+    <p>A boolean to expose <code>__dirname</code>, <code>__filename</code>, and <code>require</code> in ES modules.</p>
+  </td>
+</tr>
+<tr>
+  <td colspan="2">
+    <pre><code>    }
+  }
+}</code></pre>
+  </td>
+</tr>
+</table>
+
 DevOpts
@@ -151,4 +221,12 @@ ---
 <tr>
+  <td valign="top"><code>"cache":</code></td>
+  <td>
+    <p>A boolean for toggling the <code>.esm-cache</code> <i>(default: <code>true</code>).</i></p>
+  </td>
+</tr>
+<tr>
   <td valign="top"><code>"debug":</code></td>
-  <td><p>A boolean for unmasking stack traces.</p></td>
+  <td>
+    <p>A boolean for unmasking stack traces.</p>
+  </td>
 </tr>
@@ -158,3 +236,3 @@ <tr>
   <td>
-    <p>A boolean for enabling inline source maps.</p>
+    <p>A boolean for including inline source maps.</p>
     <p><i>Note: Automatically enabled using the Node CLI
@@ -167,4 +245,4 @@ <a href="https://nodejs.org/en/docs/inspector/"><code>--inspect</code> option</a>.</i></p>
   <td>
-    <p>A boolean for enabling parse and runtime warnings.</p>
-    <p><i>Note: The default value is <code>process.env.NODE_ENV !== "production"</code>.</i></p>
+    <p>A boolean for logging parse and runtime warnings.</p>
+    <p><i>(default: <code>process.env.NODE_ENV !== "production"</code>)</i></p>
   </td>
@@ -179,1 +257,11 @@ </tr>
 </table>
+
+Tips
+---
+* Load `@std/esm` before [`@babel/register`](https://www.npmjs.com/package/@babel/register) v7+
+* Load `@std/esm` with the *“require”* option of [AVA](https://github.com/avajs/ava#options),
+  [Mocha](https://mochajs.org/#-r---require-module-name), and [nyc](https://github.com/istanbuljs/nyc#require-additional-modules)
+* Load `@std/esm` with the `--node-arg=-r --node-arg=@std/esm` option of [tap](http://www.node-tap.org/cli/)
+* Use options `"@std/esm":"cjs"` or `"@std/esm":{"cjs":{"cache":true}}` with the Mocha [`--watch` option](https://mochajs.org/#-w---watch)
+* Use options `"@std/esm":"cjs"` with [webpack](https://webpack.js.org/)
+* When in doubt, use options `"@std/esm":"cjs"`

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

57202

increased by3.53%

Number of lines in readme file

256

increased by52.38%

No dependency changes