diff --git a/README.md b/README.md
index 9ba28b4..179a905 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,9 @@
---
-Synchronously import dynamic ES6 modules similar to CommonJS [require](https://nodejs.org/api/modules.html#requireid)
+Synchronously import dynamic ECMAScript Modules similar to CommonJS [require](https://nodejs.org/api/modules.html#requireid)
+
+Basic wrapper around [esm](https://github.com/standard-things/esm) for compatibility with both ES6 and CJS projects in NodeJS
[![Try with Replit](https://replit.com/badge?caption=Try%20with%20Replit)](https://replit.com/@nktnet1/import-sync-example#index.js)
@@ -63,7 +65,8 @@ Synchronously import dynamic ES6 modules similar to CommonJS [require](https://n
- [4. Limitations](#4-limitations)
- [5. Caveats](#5-caveats)
- [5.1. Idea](#51-idea)
- - [5.2. Approach](#52-approach)
+ - [5.2. Discovery](#52-approach)
+ - [5.3. Result](#53-result)
## 1. Installation
@@ -105,6 +108,15 @@ const { someFunction } = importSync(
);
```
+Using additional esm options as described in esm's [documentation](https://github.com/standard-things/esm#options)
+
+```javascript
+const { someFunction } = importSync(
+ 'someModule.mjs',
+ { basePath: process.cwd() }
+);
+```
+
@@ -198,9 +210,9 @@ DEALINGS IN THE SOFTWARE.
One known non-issue is that in [jest](https://jestjs.io/), calling `importSync` on
a CommonJS module returns an empty object.
-There is currently no plans to fix this issue, as the default NodeJS
-[require](https://nodejs.org/api/modules.html#requireid) should be simply be used
-instead for CommonJS imports.
+There are currently no plans to fix this issue, as the built-in NodeJS
+[require](https://nodejs.org/api/modules.html#requireid) function should be used
+instead when importing CommonJS modules.
## 5. Caveats
@@ -213,9 +225,16 @@ script that can be run by students undertaking
The dryrun serves as a sanity check before the
final submission is made, and is located in the centralised [COMP1531 course account](https://taggi.cse.unsw.edu.au/FAQ/Uploading_to_course_accounts/) at the path `~cs1531/bin`. Students who are connected to the CSE lab environment (e.g. via [VLAB](https://taggi.cse.unsw.edu.au/FAQ/VLAB_-_The_technical_details/)) can run the dryrun script from their major project repository, e.g. at the path `~z5313514/comp1531/project-backend`.
-### 5.2. Approach
+### 5.2. Discovery
+
+Initially, the [esm](https://github.com/standard-things/esm) library looked promising. However, when the global dryrun script was executed in a mock student's project directory, the following error occured:
+
+> Error [ERR_REQUIRE_ESM]: require() of ES Module /import/ravel/5/z5313515/project-backend/src/auth.js not supported.
+Instead change the require of auth.js in null to a dynamic import() which is available in all CommonJS modules
+
+This is due to the `package.json` containing `"type": "module"`, as iteration 1 of the student major project uses ESM for the seamless transition to future iterations.
-The following methods were attempted, but were unsatisfactory for our purposes:
+The following approaches were thus attempted, but were unsatisfactory for our purpose:
1. [jewire](https://github.com/nktnet1/jewire)/[rewire](https://github.com/jhnns/rewire)/[require](https://nodejs.org/api/modules.html#requireid)
- in iteration 1, the dryrun requires the import of ES6 modules, so [jewire](https://github.com/nktnet1/jewire) (which was used for the dryrun of iteration 0) was no longer satisfying our requirements
@@ -223,7 +242,7 @@ The following methods were attempted, but were unsatisfactory for our purposes:
2. [import()](https://nodejs.org/api/esm.html#import-expressions) - ECMAScript dynamic import
- this was the previous attempt at writing the dryrun
- However, it relied on asynchronous code. Since COMP1531 is **fully synchronous** (including the use of [sync-request-curl](https://github.com/nktnet1/sync-request-curl) for sending HTTP requests), this became a source of mystery and confusion for students
- - additionally, students had to append the suffix `.js` to their file imports in the project, solely for the dryrun. This resulted in ambiguous error messages and obscure dryrun requirements unrelated to the project
+ - additionally, students had to append the suffix `.js` to all of their file imports in the project solely to use the dryrun. This resulted in ambiguous error messages and obscure dryrun requirements unrelated to the project
3. [require-esm-in-cjs](https://github.com/SamGoody/require-esm-in-cjs)
- this library utilises [deasync](https://github.com/abbr/deasync), which when used in NodeJS for Jest tests, could hang indefinitely as seen in Jest's issue [#9729](https://github.com/jestjs/jest/issues/9729)
- since COMP1531 uses Jest as the sole testing framework, [deasync](https://github.com/abbr/deasync) could not be used as a dependency
@@ -233,3 +252,16 @@ The following methods were attempted, but were unsatisfactory for our purposes:
- [fibers](https://github.com/laverdet/node-fibers): obsolete and does not work for node versions later than 16
- [synchronize](https://github.com/al6x/synchronize): documentation link gives 404 and has fiber as a dependency
- [sync/node-sync](https://github.com/ybogdanov/node-sync): uses fiber (note: "redblaze/node-sync" on github, "sync" on npm)
+
+### 5.3. Result
+
+Upon a more thorough investigation into the initial issue with the
+[esm](https://github.com/standard-things/esm) module, the cause was the
+introduction of the exception starting from NodeJS version 13, as noted in
+[@fregante](https://github.com/fregante)'s comment:
+- https://github.com/standard-things/esm/issues/855#issuecomment-558319872.
+
+Further down the thread was a link to the solution by [@guybedford](https://github.com/guybedford)
+- https://github.com/standard-things/esm/issues/868#issuecomment-594480715
+
+which removes the exception through module extension and serves as a satisfactory workaround.
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 01afed0..61f51ee 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "import-sync",
- "version": "0.0.0",
+ "version": "0.0.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "import-sync",
- "version": "0.0.0",
+ "version": "0.0.1",
"license": "MIT",
"dependencies": {
"esm": "^3.2.25"
diff --git a/package.json b/package.json
index 0f48e67..48e27c5 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,7 @@
"type": "git",
"url": "https://github.com/nktnet1/import-sync"
},
- "version": "0.0.0",
+ "version": "0.0.1",
"files": [
"dist"
],