doc: copyedit esm.md

This provides a number of minor style adjustments and small corrections to esm.md text. Co-authored-by: Guy Bedford <[email protected]> PR-URL: #35414 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Guy Bedford <[email protected]> Reviewed-By: Derek Lewis <[email protected]> Reviewed-By: Geoffrey Booth <[email protected]>
nodejs · danielleadams · Oct 7, 2020 · Sep 27, 2020 · Sep 28, 2020 · Sep 27, 2020
commit 95c62a1dca871277ccad37ac8403ec2f3dbcc3da
diff --git a/doc/api/esm.md b/doc/api/esm.md
@@ -122,13 +122,13 @@ added: v12.10.0
 
 * `text/javascript` for ES Modules
 * `application/json` for JSON
-* `application/wasm` for WASM.
+* `application/wasm` for Wasm
 
 `data:` URLs only resolve [_Bare specifiers_][Terminology] for builtin modules
 and [_Absolute specifiers_][Terminology]. Resolving
-[_Relative specifiers_][Terminology] will not work because `data:` is not a
+[_Relative specifiers_][Terminology] does not work because `data:` is not a
 [special scheme][]. For example, attempting to load `./foo`
-from `data:text/javascript,import "./foo";` will fail to resolve since there
+from `data:text/javascript,import "./foo";` fails to resolve because there
 is no concept of relative resolution for `data:` URLs. An example of a `data:`
 URLs being used is:
 
@@ -200,7 +200,7 @@ from which to resolve from:
 })();
 ```
 
-This function is asynchronous since the ES module resolver in Node.js is
+This function is asynchronous because the ES module resolver in Node.js is
 asynchronous. With the introduction of [Top-Level Await][], these use cases
 will be easier as they won't require an async function wrapper.
 
@@ -219,8 +219,8 @@ ES modules are resolved and cached based upon
 [URL](https://url.spec.whatwg.org/) semantics. This means that files containing
 special characters such as `#` and `?` need to be escaped.
 
-Modules will be loaded multiple times if the `import` specifier used to resolve
-them have a different query or fragment.
+Modules are loaded multiple times if the `import` specifier used to resolve
+them has a different query or fragment.
 
 ```js
 import './foo.mjs?query=1'; // loads ./foo.mjs with query of "?query=1"
@@ -295,8 +295,8 @@ console.log(cjs === cjsSugar);
 //   true
 ```
 
-The ECMAScript Module Namespace representation of a CommonJS module will always
-be a namespace with a `default` export key pointing to the CommonJS
+The ECMAScript Module Namespace representation of a CommonJS module is always
+a namespace with a `default` export key pointing to the CommonJS
 `module.exports` value.
 
 This Module Namespace Exotic Object can be directly observed either when using
@@ -312,19 +312,19 @@ console.log(m === await import('cjs'));
 //   true
 ```
 
-For better compatibility with existing usage in the JS ecosystem, Node.js will
-in addition attempt to determine the CommonJS named exports of every imported
+For better compatibility with existing usage in the JS ecosystem, Node.js
+in addition attempts to determine the CommonJS named exports of every imported
 CommonJS module to provide them as separate ES module exports using a static
 analysis process.
 
-For example, a CommonJS module written:
+For example, consider a CommonJS module written:
 
 ```js
 // cjs.cjs
 exports.name = 'exported';
 ```
 
-will support named imports in ES modules:
+The preceding module supports named imports in ES modules:
 
 <!-- eslint-disable no-duplicate-imports -->
 ```js
@@ -348,8 +348,8 @@ directly on the ES module namespace when the module is imported.
 Live binding updates or new exports added to `module.exports` are not detected
 for these named exports.
 
-The detection of named exports is based on common syntax patterns but will not
-always correctly detect named exports, in these cases using the default
+The detection of named exports is based on common syntax patterns but does not
+always correctly detect named exports. In these cases, using the default
 import form described above can be a better option.
 
 Named exports detection covers many common export patterns, reexport patterns
@@ -358,7 +358,7 @@ semantics implemented.
 
 ## Builtin modules
 
-[Core modules][] will provide named exports of their public API. A
+[Core modules][] provide named exports of their public API. A
 default export is also provided which is the value of the CommonJS exports.
 The default export can be used for, among other things, modifying the named
 exports. Named exports of builtin modules are updated only by calling
@@ -415,11 +415,11 @@ and are loaded using the CJS loader. [WHATWG JSON modules specification][] are
 still being standardized, and are experimentally supported by including the
 additional flag `--experimental-json-modules` when running Node.js.
 
-When the `--experimental-json-modules` flag is included both the
-`commonjs` and `module` mode will use the new experimental JSON
-loader. The imported JSON only exposes a `default`, there is no
+When the `--experimental-json-modules` flag is included, both the
+`commonjs` and `module` mode use the new experimental JSON
+loader. The imported JSON only exposes a `default`. There is no
 support for named exports. A cache entry is created in the CommonJS
-cache, to avoid duplication. The same object will be returned in
+cache to avoid duplication. The same object is returned in
 CommonJS if the JSON module has already been imported from the
 same path.
 
@@ -523,7 +523,7 @@ The `conditions` property on the `context` is an array of conditions for
 for looking up conditional mappings elsewhere or to modify the list when calling
 the default resolution logic.
 
-The current [package exports conditions][Conditional Exports] will always be in
+The current [package exports conditions][Conditional Exports] are always in
 the `context.conditions` array passed into the hook. To guarantee _default
 Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
 `context.conditions` array passed to it _must_ include _all_ elements of the
@@ -593,7 +593,7 @@ Note: These types all correspond to classes defined in ECMAScript.
 * The specific [`TypedArray`][] object is a [`Uint8Array`][].
 
 Note: If the source value of a text-based format (i.e., `'json'`, `'module'`) is
-not a string, it will be converted to a string using [`util.TextDecoder`][].
+not a string, it is converted to a string using [`util.TextDecoder`][].
 
 ```js
 /**
@@ -704,15 +704,15 @@ export async function transformSource(source, context, defaultTransformSource) {
 
 * Returns: {string}
 
-Sometimes it can be necessary to run some code inside of the same global scope
-that the application will run in. This hook allows to return a string that will
-be ran as sloppy-mode script on startup.
+Sometimes it might be necessary to run some code inside of the same global scope
+that the application runs in. This hook allows the return of a string that is
+run as sloppy-mode script on startup.
 
 Similar to how CommonJS wrappers work, the code runs in an implicit function
 scope. The only argument is a `require`-like function that can be used to load
 builtins like "fs": `getBuiltin(request: string)`.
 
-If the code needs more advanced `require` features, it will have to construct
+If the code needs more advanced `require` features, it has to construct
 its own `require` using  `module.createRequire()`.
 
 ```js
@@ -807,13 +807,9 @@ import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffee
 console.log(VERSION);
 ```
 
-With this loader, running:
-
-```bash
-node --experimental-loader ./https-loader.mjs ./main.mjs
-```
-
-Will print the current version of CoffeeScript per the module at the URL in
+With the preceding loader, running
+`node --experimental-loader ./https-loader.mjs ./main.mjs`
+prints the current version of CoffeeScript per the module at the URL in
 `main.mjs`.
 
 #### Transpiler loader
@@ -894,13 +890,9 @@ console.log "Brought to you by Node.js version #{version}"
 export scream = (str) -> str.toUpperCase()
 ```
 
-With this loader, running:
-
-```console
-node --experimental-loader ./coffeescript-loader.mjs main.coffee
-```
-
-Will cause `main.coffee` to be turned into JavaScript after its source code is
+With the preceding loader, running
+`node --experimental-loader ./coffeescript-loader.mjs main.coffee`
+causes `main.coffee` to be turned into JavaScript after its source code is
 loaded from disk but before Node.js executes it; and so on for any `.coffee`,
 `.litcoffee` or `.coffee.md` files referenced via `import` statements of any
 loaded file.