esm-sync 3.3.3-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright esm contributors
+
+Based on reify, copyright Ben Newman <https://github.com/benjamn/reify>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @nktnet1/esm
+
+> _Part of [HTTP Toolkit](https://nktnet1.com): powerful tools for building, testing & debugging HTTP(S)_
+
+**This is a forked version of the [esm package](https://www.npmjs.com/package/esm)**: the brilliantly simple, babel-less, bundle-less ECMAScript module loader (which is now unmaintained). This fork includes:
+
+* Assorted updates from the [esm-wallaby fork](https://www.npmjs.com/package/esm-wallaby) adding support for ES modules containing new ES syntax, supporting modern Node versions (at least up to v21), and supporting `node:*` imports.
+* Support for modules that use the `const require = createRequire(...)` pattern (or declare any other global `require` variable) which are otherwise unusable with `esm`.
+* Support for modules that use only an `exports` map in their package.json, without a `main` field, which are otherwise unresolveable (reporting "Cannot find module", even though `import()` works correctly).
+
+Install
+---
+
+Run `npm i @nktnet1/esm` or `yarn add @nktnet1/esm`.
+
+Getting started
+---
+
+There are two ways to enable `@nktnet1/esm`.
+
+1. Enable `@nktnet1/esm` for packages:
+
+   Use `@nktnet1/esm` to load the main ES module and export it as CommonJS.
+
+    __index.js__
+    ```js
+    // Set options as a parameter, environment variable, or rc file.
+    require = require("@nktnet1/esm")(module/*, options*/)
+    module.exports = require("./main.js")
+    ```
+    __main.js__
+    ```js
+    // ESM syntax is supported.
+    export {}
+    ```
+
+2. Enable `@nktnet1/esm` for local runs:
+
+    ```shell
+    node -r @nktnet1/esm main.js
+    ```
+    :bulb: Omit the filename to enable `@nktnet1/esm` in the REPL.
+
+Features
+---
+
+:clap: By default, :100: percent CJS interoperability is enabled so you can get stuff done.<br>
+:lock: `.mjs` files are limited to basic functionality without support for `@nktnet1/esm` options.
+
+Out of the box `@nktnet1/esm` just works, no configuration necessary, and supports:
+
+* Passing all applicable [test262](https://github.com/tc39/test262) compliance tests
+* [`import`](https://ponyfoo.com/articles/es6-modules-in-depth#import)/[`export`](https://ponyfoo.com/articles/es6-modules-in-depth#export)
+* [`import.meta`](https://github.com/tc39/proposal-import-meta)
+* [Dynamic `import`](https://github.com/tc39/proposal-dynamic-import)
+* [Live bindings](https://ponyfoo.com/articles/es6-modules-in-depth#bindings-not-values)
+* [File URI scheme](https://en.wikipedia.org/wiki/File_URI_scheme)
+* Node `stdin`, [`--eval`](https://nodejs.org/api/cli.html#cli_e_eval_script), [`--print`](https://nodejs.org/api/cli.html#cli_p_print_script) flags
+* Node [`--check`](https://nodejs.org/api/cli.html#cli_c_check) flag _(Node 10+)_
+
+Options
+---
+
+Specify options with one of the following:
+
+* `"esm"` field in `package.json`
+* CJS/ESM in an `.esmrc.js`, `.esmrc.cjs`, or `.esmrc.mjs` file
+* [JSON6](https://github.com/d3x0r/json6) in an `.esmrc` or `.esmrc.json` file
+* JSON6 or file path in the `ESM_OPTIONS` environment variable
+* `ESM_DISABLE_CACHE` environment variable
+
+<table>
+<tr>
+  <td colspan="2"><code>{</code></td>
+</tr>
+<tr>
+  <td valign="top"><code>"cjs":true</code></td>
+  <td>
+    <p>A boolean or object for toggling CJS features in ESM.</p>
+    <details>
+      <summary>Features</summary>
+      <table>
+      <tr>
+        <td colspan="2"><code>{</code></td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"cache":true</code></td>
+        <td>
+          <p>A boolean for storing ES modules in <code>require.cache</code>.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"esModule":true</code></td>
+        <td>
+          <p>A boolean for <code>__esModule</code> interoperability.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"extensions":true</code></td>
+        <td>
+          <p>A boolean for respecting <code>require.extensions</code> in ESM.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"mutableNamespace":true</code></td>
+        <td>
+          <p>A boolean for mutable <a href="https://ponyfoo.com/articles/es6-modules-in-depth#import-all-the-things">namespace objects</a>.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"namedExports":true</code></td>
+        <td>
+          <p>A boolean for <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":true</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 ESM.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"vars":true</code></td>
+        <td>
+          <p>A boolean for <code>__dirname</code>, <code>__filename</code>, and <code>require</code> in ESM.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"dedefault":false</code></td>
+        <td>
+          <p>A boolean for requiring ES modules without the dangling <code>require().default</code>.</p>
+        </td>
+      </tr>
+      <tr>
+        <td valign="top"><code>"topLevelReturn":false</code></td>
+        <td>
+          <p>A boolean for top-level <code>return</code> support.</p>
+        </td>
+      </tr>
+      <tr>
+        <td colspan="2"><code>}</code></td>
+      </tr>
+      </table>
+    </details>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"mainFields":["main"]</code></td>
+  <td>
+    <p>An array of fields checked when importing a package.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"mode":"auto"</code></td>
+  <td>
+    <p>A string mode:</p>
+    <ul>
+      <li><code>"auto"</code> detect files with <code>import</code>, <code>import.meta</code>, <code>export</code>,<br><a href="https://github.com/tc39/proposal-modules-pragma"><code>"use module"</code></a>, or <code>.mjs</code> as ESM.</li>
+      <li><code>"all"</code> files besides those with <code>"use script"</code> or <code>.cjs</code> are treated as ESM.</li>
+      <li><code>"strict"</code> to treat <strong>only</strong> <code>.mjs</code> files as ESM.</li>
+    </ul>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"await":false</code></td>
+  <td>
+    <p>A boolean for <a href="https://github.com/tc39/proposal-top-level-await">top-level <code>await</code></a> in modules without ESM exports. <em>(Node 10+)</em></p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"force":false</code></td>
+  <td>
+    <p>A boolean to apply these options to all module loads.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"wasm":false</code></td>
+  <td>
+    <p>A boolean for <a href="https://nodejs.org/api/globals.html#globals_webassembly">WebAssembly</a> module support. <em>(Node 8+)</em></p>
+  </td>
+</tr>
+<tr>
+  <td colspan="2"><code>}</code></td>
+</tr>
+</table>
+
+DevOpts
+---
+
+<table>
+<tr>
+  <td colspan="2"><code>{</code></td>
+</tr>
+<tr>
+  <td valign="top"><code>"cache":true</code></td>
+  <td>
+    <p>A boolean for toggling cache creation or a cache directory path.</p>
+  </td>
+</tr>
+<tr>
+  <td valign="top"><code>"sourceMap":false</code></td>
+  <td>
+    <p>A boolean for including inline source maps.</p>
+  </td>
+</tr>
+<tr>
+  <td colspan="2"><code>}</code></td>
+</tr>
+</table>
+
+Tips
+---
+
+### Bundling
+
+* For bundlers like [`browserify`](http://browserify.org/)+[`esmify`](https://github.com/mattdesl/esmify),
+  [`parcel-bundler`](https://parceljs.org/), and [`webpack`](https://webpack.js.org/)
+  add a `"module"` field to `package.json` pointing to the main ES module.
+  ```json
+  "main": "index.js",
+  "module": "main.js"
+  ```
+
+  :bulb: This is automagically done with `npm init esm` or `yarn create esm`.
+
+### Extensions
+
+* Enable `@nktnet1/esm` for [`wallaby.js`](https://wallabyjs.com/) following their
+  [integration example](https://wallabyjs.com/docs/integration/node.html#es-modules).
+
+### Loading
+
+* Load `@nktnet1/esm` before loaders/monitors like
+  [`@babel/register`](https://babeljs.io/docs/en/next/babel-register.html),
+  [`newrelic`](https://github.com/newrelic/node-newrelic),
+  [`sqreen`](https://docs.sqreen.io/sqreen-for-nodejs/getting-started-2/), and
+  [`ts-node`](https://github.com/TypeStrong/ts-node#programmatic).
+
+* Load `@nktnet1/esm` for [`jasmine`](https://jasmine.github.io/) using the
+  [`"helpers"`](https://jasmine.github.io/setup/nodejs.html#configuration)
+  field in `jasmine.json`:
+  ```json
+  "helpers": [
+    "node_modules/@nktnet1/esm"
+  ]
+  ```
+
+* Load `@nktnet1/esm` with “node-args" options of:<br>
+  - [`pm2`](https://pm2.io/doc/en/runtime/reference/pm2-cli/#pm2-flags): `--node-args="-r @nktnet1/esm"`
+
+* Load `@nktnet1/esm` with “require” options of
+  [`ava`](https://github.com/avajs/ava/blob/master/docs/recipes/es-modules.md),
+  [`mocha`](https://mochajs.org/#-require-module-r-module),
+  [`nodemon`](https://nodemon.io/),
+  [`nyc`](https://github.com/istanbuljs/nyc#require-additional-modules),
+  [`qunit`](https://github.com/qunitjs/qunit/releases/tag/2.6.0),
+  [`tape`](https://github.com/substack/tape#preloading-modules), and
+  [`webpack`](https://webpack.js.org/api/cli/#config-options).
+
+  :bulb: Builtin `require` cannot sideload `.mjs` files. However, `.js` files
+  can be sideloaded or `.mjs` files may be loaded with dynamic `import`.