V8

.gitignore

@@ -1,10 +1,17 @@
-/es5/
 /node_modules/
+
+# tooling artefacts
+/docs/.sass-cache/
+.eslintcache
 npm-debug.log
-/dist/
+
+# test artifacts
 coverage/
 /test/fixtures/built-sw.js
 .nyc_output
-.eslintcache
+
+# built files
+/es5
+/esm
+/cjs
 /docs/_site/
-/docs/.sass-cache/

.npmignore

@@ -1,17 +1,18 @@
-/test/
 /.circleci/
-.eslintrc
-ISSUE_TEMPLATE
-karma.conf.js
-Makefile
-README.md
-/docs/
 /.nyc_output/
 /coverage/
+/docs/
+/src/
+/test/
+.codeclimate.yml
 .eslint*
 .gitignore
+.prettierrc
 Gemfile
 Gemfile.lock
-.prettierrc
-.codeclimate.yml
+ISSUE_TEMPLATE
+karma.conf.js
+Makefile
 package-lock.json
+README.md
+rollup.config.js

Makefile

@@ -19,10 +19,13 @@ test-node6: transpile
 
 lint-ci:
 	eslint --ignore-pattern test/fixtures/* src test
+	prettier *.md
+	dtslint --expectOnly types
 
 lint:
 	eslint --cache --fix .
 	prettier --write *.md
+	dtslint --expectOnly types
 
 coverage-report:
 	nyc --reporter=lcovonly --reporter=text mocha test/server.js
@@ -34,11 +37,10 @@ local-coverage:
 transpile:
 	babel src --out-dir es5
 
-bundle:
-	webpack --mode development \
-	--output-library fetchMock \
-	--entry ./es5/client.js \
-	--output-filename ./es5/client-bundle.js
+build: transpile
+	if [ ! -d "cjs" ]; then mkdir cjs; fi
+	cp -r src/* cjs
+	rollup -c rollup.config.js
 
 docs:
 	cd docs; jekyll serve build --watch

docs/_api-inspection/fundamentals.md

@@ -14,25 +14,29 @@ parameters:
           Retrieve all calls made to `fetch`
       - types:
         - true
+        - '"matched"'
         content: |-
-          Retrieve all calls to `fetch` matched by some route defined by `fetch-mock`. `fetchMock.MATCHED` is an alias for `true` and may be used to make tests more readable
+          Retrieve all calls to `fetch` matched by some route defined by `fetch-mock`. The string `'matched'` can be used instead of `true` to make tests more readable
         examples:
           - |-
             const {MATCHED, fetchMock} = require('fetch-mock');
             ...
             fetchMock.calls(MATCHED)
       - types:
         - false
+        - '"unmatched"'
         content: |-
-          Retrieves all calls to `fetch` not matched by a route (i.e. those handled by `catch()`, `spy()` or the `fallbackToNetwork` option). `fetchMock.UNMATCHED` is an alias for `false` and may be used to make tests more readable
+          Retrieve all calls to `fetch` not matched by some route defined by `fetch-mock`. The string `'unmatched'` can be used instead of `false` to make tests more readable
         examples:
           - |-
             const {UNMATCHED, fetchMock} = require('fetch-mock');
             ...
             fetchMock.calls(UNMATCHED)
       - name: routeIdentifier
         types:
-          - String|RegExp|function
+          - String
+          - RegExp
+          - function
         content: |-
           All routes have an identifier:
           - If it's a [named route](#api-mockingmock_options), the identifier is the route's `name`
@@ -41,7 +45,9 @@ parameters:
           All calls that were handled by the route with the given identifier will be retrieved
       - name: matcher
         types:
-          - String|RegExp|function
+          - String
+          - RegExp
+          - function
         content: |-
           Any matcher compatible with the [mocking api](#api-mockingmock_matcher) can be passed in to filter the calls arbitrarily. The matcher will be executed using exactly the same rules as the mocking api
   - name: options
@@ -82,7 +88,7 @@ content_markdown: |-
   ...
   // this will retrieve calls handled by either route
   fm.called(/user\/biff/)
-  // this will retrieve only calls handeld by the second route
-  fm.called(/user\/biff/)
+  // this will retrieve only calls handled by the second route
+  fm.called(matcherRX)
   ```
 ---

docs/_usage/importing.md

@@ -0,0 +1,40 @@
+---
+title: Importing the correct version
+position: 4
+parentItem: installation
+content_markdown: |-
+
+  The JS ecosystem is in a transitional period between module systems, and there are also a number of different build tools available, all with their own idosyncratic opinions about how JS should be compiled. The following detail may help debug any problems, and a few known workarounds are listed below.
+
+  #### Built files
+  In general `server` refers to the version of the source code designed for running in nodejs, whereas `client` refers to the version designed to run in the browser. As well as this distinction, fetch-mock builds several versions of itself:
+  - `/cjs` directory - this contains a copy of the source files (which are currently written as commonjs modules). They are copied here in order to prevent direct requires from `/src`, which could make migrating the src to ES modules troublesome. `client.js` and `server.js` are the entry points. The directory also contains a `package.json` file specifying that the directory contains commonjs modules.
+  - `/esm` directory - This contains builds of fetch-mock, exported as ES modules. `client.mjs` and `server.mjs` are the entry points. The bundling tool used is [rollup](https://rollupjs.org).
+  - `/es5` directory - This contains builds of fetch-mock which do not use any JS syntax not included in the [ES5 standard](https://es5.github.io/), i.e. excludes recent additions to the language. It contains 4 entry points:
+    - `client.js` and `server.js`, both of which are commonjs modules
+    - `client-legacy.js`, which is the same as `client.js`, but includes some babel polyfill bootstrapping to ease running it in older environments
+    - `client-bundle.js`, `client-legacy-bundle.js`, which are standalone [UMD](https://github.com/umdjs/umd) bundles of the es5 client code that can be included in the browser using an ordinary script tag. The bundling tool used is [rollup](https://rollupjs.org).
+
+  #### Importing the right file
+  The package.json file references a selection of the above built files:
+  ```json
+  {
+    "main": "./cjs/server.js",
+    "browser": "./esm/client.js",
+    "module": "./esm/server.js",
+  }
+  ```
+  These are intended to target the most common use cases at the moment:
+  - nodejs using commonjs
+  - nodejs using ES modules
+  - bundling tools such as webpack
+
+  In most cases, your environment & tooling will use the config in package.json to import the correct file when you `import` or `require` `fetch-mock` by its name only.
+
+  However, `import`/`require` will sometimes get it wrong. Below are a few scenarios where you may need to directly reference a different entry point.
+
+  - If your client-side code or tests do not use a loader that respects the `browser` field of `package.json` use `require('fetch-mock/es5/client')` or `import fetchMock from 'fetch-mock/esm/client'`.
+  - When not using any bundler in the browser, use one of the following as the src of a script tag: `node_modules/fetch-mock/es5/client-bundle.js`, `node_modules/fetch-mock/es5/client-legacy-bundle.js`. This loads fetch-mock into the `fetchMock` global variable.
+  - For Node.js 6 or lower use `require('fetch-mock/es5/server')`
+---
+

docs/_usage/installation.md

@@ -9,20 +9,16 @@ content_markdown: |-
   npm install --save-dev fetch-mock
   ```
 
-  In most environments use one of the following in your test files
+  fetch-mock supports both [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [commonjs](https://requirejs.org/docs/commonjs.html). The following should work in most environments. Check the [importing the correct version](#usageimporting) section of the docs if you experience problems.
 
+  ## ES modules
   ```js
-  const fetchMock = require('fetch-mock');
-
-  // Exposes constants that will make tests more readable
-  const { fetchMock, MATCHED, UNMATCHED } = require('fetch-mock');
+  import fetchMock from 'fetch-mock';
   ```
 
-  Some exceptions include:
-
-  - If your client-side code or tests do not use a loader that respects the `browser` field of `package.json` use `require('fetch-mock/es5/client')`.
-  - If you need to use fetch-mock without commonjs, you can include the precompiled `node_modules/fetch-mock/es5/client-bundle.js` in a script tag. This loads fetch-mock into the `fetchMock` global variable.
-  - For server side tests running in Node.js 6 or lower use<br>
-  `require('fetch-mock/es5/server')`
+  ## Commonjs
+  ```js
+  const fetchMock = require('fetch-mock');
+  ```
 ---