ESM support

.gitignore

@@ -2,4 +2,3 @@ npm-debug.log*
 
 #ignore node_modules, as the node project is not "deployed" per se: http://www.mikealrogers.com/posts/nodemodules-in-git.html
 /node_modules
-

.travis.yml

@@ -1,9 +1,9 @@
 language: node_js
 node_js:
-  - 6
   - 8
   - 10
   - 12
+  - 13
   - 14
 before_install: npm i -g npm@6
 script: npm run test:ci

README.md

@@ -66,6 +66,75 @@ after the absolute path resolved to by `'./some/path'`.
 
 Spiffy!
 
+> Note: `defaultFakeCreator` is not supported for ES Module stubbing
+
+## ES Modules support
+
+Quibble supports ES Modules. Quibble implements ES module support using [ES Module
+Loaders](https://nodejs.org/api/esm.html#esm_experimental_loaders) which are the official way to
+"patch" Node.js' module loading mechanism for ESM.
+
+> Note that Loader support is currently experimental and unstable. We will be doing our best
+  to track the changes in the specification for the upcoming Node.js versions. Also note that
+  Quibble ESM support is tested only for versions 13 and above.
+
+To use Quibble support, you must run Node with the `quibble` package as the loader:
+
+```sh
+node --loader=quibble ...
+```
+
+Most test runners allow you to specify this in their command line, e.g. for Mocha:
+
+```sh
+mocha --loader=quibble ...
+```
+
+The `quibble` loader will enable the replacement of the ES modules with the stubs you specify, and
+without it, the stubbing will be ignored.
+
+### Restrictions on ESM
+
+* `defaultFakeCreator` is not yet supported.
+
+### `quibble` ESM API
+
+The API is similar to the CommonJS API, but uses `quibble.esm` function, and is async:
+
+```js
+// a-module.mjs (ESM)
+export const life = 42;
+export default 'universe';
+
+// uses-a-module.mjs
+import universe, {life} from './a-module.mjs';
+
+console.log(life, universe);
+
+(async function () {
+  await quibble.esm('./a-module.mjs', {life: 41}, 'replacement universe');
+
+  await import('./uses-some-module.mjs');
+  // ==> logs: 41, replacement universe
+})();
+```
+
+The parameters to `quibble` for ESM modules are:
+
+1. the module path: similar to CommonJS, the path is relative to the directory you are in. It is
+   resolved the ESM way, so if you're using a relative path, you must specify the filename,
+   including the extension.
+
+* `quibble.reset` works the same as for CommonJS modules
+
+ESM support also exposes the function `quibble.esmImportWithPath` which both imports a module and
+resolves the path to the module that is the package's entry point:
+
+* `async quibble.esmImportWithPath(importPath)`: imports a module, just like `import(importPath)`,
+  but returns an object with two properties:
+  * `module`: the module returned by `await import(importPath)`.
+  * `modulePath`: the full path to the module (file) that is the entry point to the package/module.
+
 ## How's it different?
 
 A few things that stand out about quibble:

example-esm/.gitignore

@@ -0,0 +1 @@
+/node_modules

example-esm/lib/animals/bear.mjs

@@ -0,0 +1 @@
+export default function () { return 'a real bear' }

example-esm/lib/animals/lion.mjs

@@ -0,0 +1 @@
+export default function () { return 'a real lion' }

example-esm/lib/zoo.mjs

@@ -0,0 +1,11 @@
+import lion from './animals/lion.mjs'
+import bear from './animals/bear.mjs'
+
+export default function () {
+  return {
+    animals: [
+      lion(),
+      bear()
+    ]
+  }
+}