esm: fix hook mistypes and links to types

Prior to this commit, the custom loader hooks were:
* missing the Node.js API ref docs types
* missing the function signature from their sections
* linking directly to the specification (not customary)
* had an inconsistent non-nullable JSDoc promise return
* had JSDoc object properties that weren't alpha-sorted
* designated set of non-nullable types when single was fine

Notes:
    https://www.typescriptlang.org/play/index.html?strictNullChecks=true&useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+k28ApgMYEBmB1yUMCK6WmbkftAeyIATArgJDsALkgBCAILJUATwA8eQqQB8AGl58kyakVwBVAEoAZGbIAUG4iUgAfSAFcR1JkWrCAlHrQkGQUgibUAB64vByoGJgAYh604kIUwl6IbgA2uObU2ALZAG7UMUa4bshE2FgACsgCaATY1KqY7sjZMg6kwVpkbMDgkfACyLiQiNjKRLSQDMmpRJBGhSXU9jT0TCw6kGG4kbj7GQxZufnrpX5YUAeSkx2GxmZWkAC8kEQ52cGfD3CUQA3PdGJBbABZRC4AAWADpUCImrZblpIAAGeEAVluHWAwEgAGUmtRAaJlvD7nwCZAEuNKKTIAzENk-lQ6IxmMhsKcBIy0GTaG48E1INkBCQCPMGAy1kVio4qXwaYT5NkAO6IZS1CpVFaIFYCABGACs6JMBAxIHCybLkPEqt1IOp8I4BsqVXrqncVSqnTIXiYLJZIAB+al+77UDWQENbTm7ZD7INvSx+eGwozWqSRv0+WPxjk7bkZrNeQIqsigviDPjgqEwhFI4Qo26qTE4vGQWnyIgCW3IcliCRET2qyAAdVhxgOrOyjkgAAMzhc8gUFdQl-tbVNkCQ3IKTLVaIbIMayWgBKJdsJ4ZAAJIrOEtSO00+tSBiADktUQwlEPpDQHGch2KVk3DtBk0BhWhYUXMIKVHVlIFGcZcGwcdVmoSofVXHJ12uTZiy5PZfSjeFKMOY5Kz9RCR0kGQAG1KPhaiojYoQkMkfZv2AwcAFp6OWb8AF1aOCPwa2Ce5aQAES8FgbX5AA5a9qHhU1antKY2WZQdKG2UieU9b0Vnwy4Nw2BMSzI9iTkgCzCM3KTwDIIA
    https://closure-compiler.appspot.com/home#code%3D%252F%252F%2520%253D%253DClosureCompiler%253D%253D%250A%252F%252F%2520%2540compilation_level%2520ADVANCED_OPTIMIZATIONS%250A%252F%252F%2520%2540warning_level%2520VERBOSE%250A%252F%252F%2520%2540jscomp_error%2520strictCheckTypes%250A%252F%252F%2520%2540language_out%2520ECMASCRIPT_NEXT%250A%252F%252F%2520%2540checks_only%250A%252F%252F%2520%253D%253D%252FClosureCompiler%253D%253D%250A%250A%252F**%250A%2520*%2520%2540param%2520%257Bstring%257D%2520specifier%250A%2520*%2520%2540param%2520%257B%257B%250A%2520*%2520%2520%2520conditions%253A%2520!Array%253Cstring%253E%252C%250A%2520*%2520%2520%2520parentURL%253A%2520!(string%2520%257C%2520undefined)%252C%250A%2520*%2520%257D%257D%2520context%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultResolve%250A%2520*%2520%2540returns%2520%257BPromise%253C%257B%2520url%253A%2520string%2520%257D%253E%257D%250A%2520*%252F%250Aexport%2520async%2520function%2520resolve(specifier%252C%2520context%252C%2520defaultResolve)%2520%257B%250A%2520%2520const%2520%257B%2520parentURL%2520%253D%2520null%2520%257D%2520%253D%2520context%253B%250A%2520%2520if%2520(Math.random()%2520%253E%25200.5)%2520%257B%2520%252F%252F%2520Some%2520condition.%250A%2520%2520%2520%2520%252F%252F%2520For%2520some%2520or%2520all%2520specifiers%252C%2520do%2520some%2520custom%2520logic%2520for%2520resolving.%250A%2520%2520%2520%2520%252F%252F%2520Always%2520return%2520an%2520object%2520of%2520the%2520form%2520%257Burl%253A%2520%253Cstring%253E%257D.%250A%2520%2520%2520%2520return%2520%257B%250A%2520%2520%2520%2520%2520%2520url%253A%2520parentURL%2520%253F%250A%2520%2520%2520%2520%2520%2520%2520%2520new%2520URL(specifier%252C%2520parentURL).href%2520%253A%250A%2520%2520%2520%2520%2520%2520%2520%2520new%2520URL(specifier).href%252C%250A%2520%2520%2520%2520%257D%253B%250A%2520%2520%257D%250A%2520%2520if%2520(Math.random()%2520%253C%25200.5)%2520%257B%2520%252F%252F%2520Another%2520condition.%250A%2520%2520%2520%2520%252F%252F%2520When%2520calling%2520%2560defaultResolve%2560%252C%2520the%2520arguments%2520can%2520be%2520modified.%2520In%2520this%250A%2520%2520%2520%2520%252F%252F%2520case%2520it's%2520adding%2520another%2520value%2520for%2520matching%2520conditional%2520exports.%250A%2520%2520%2520%2520return%2520defaultResolve(specifier%252C%2520%257B%250A%2520%2520%2520%2520%2520%2520...context%252C%250A%2520%2520%2520%2520%2520%2520conditions%253A%2520%255B...context.conditions%252C%2520'another-condition'%255D%252C%250A%2520%2520%2520%2520%257D)%253B%250A%2520%2520%257D%250A%2520%2520%252F%252F%2520Defer%2520to%2520Node.js%2520for%2520all%2520other%2520specifiers.%250A%2520%2520return%2520defaultResolve(specifier%252C%2520context%252C%2520defaultResolve)%253B%250A%257D

PR-URL: https://github.com/nodejs/node/pull/34240
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>

1 files changed, 58 insertions, 30 deletions

diff --git a/doc/api/esm.md b/doc/api/esm.md
index ed4e6482bf..bdbac7b695 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -510,11 +510,19 @@ CommonJS modules loaded.
 
 ### Hooks
 
-#### <code>resolve</code> hook
+#### `resolve(specifier, context, defaultResolve)`
 
 > Note: The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
+* `specifier` {string}
+* `context` {Object}
+  * `conditions` {string[]}
+  * `parentURL` {string}
+* `defaultResolve` {Function}
+* Returns: {Object}
+  * `url` {string}
+
 The `resolve` hook returns the resolved file URL for a given module specifier
 and parent URL. The module specifier is the string in an `import` statement or
 `import()` expression, and the parent URL is the URL of the module that imported
@@ -535,11 +543,11 @@ Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
 /**
  * @param {string} specifier
  * @param {{
+ *   conditions: !Array<string>,
  *   parentURL: !(string | undefined),
- *   conditions: !(Array<string>),
  * }} context
  * @param {Function} defaultResolve
- * @returns {!(Promise<{ url: string }>)}
+ * @returns {Promise<{ url: string }>}
  */
 export async function resolve(specifier, context, defaultResolve) {
   const { parentURL = null } = context;
@@ -565,30 +573,35 @@ export async function resolve(specifier, context, defaultResolve) {
 }
 ```
 
-#### <code>getFormat</code> hook
+#### `getFormat(url, context, defaultGetFormat)`
 
 > Note: The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
+* `url` {string}
+* `context` {Object}
+* `defaultGetFormat` {Function}
+* Returns: {Object}
+  * `format` {string}
+
 The `getFormat` hook provides a way to define a custom method of determining how
 a URL should be interpreted. The `format` returned also affects what the
 acceptable forms of source values are for a module when parsing. This can be one
 of the following:
 
-| `format` | Description | Acceptable Types For `source` Returned by `getSource` or `transformSource` |
-| --- | --- | --- |
-| `'builtin'` | Load a Node.js builtin module | Not applicable |
-| `'commonjs'` | Load a Node.js CommonJS module | Not applicable |
-| `'dynamic'` | Use a [dynamic instantiate hook][] | Not applicable |
-| `'json'` | Load a JSON file | { [ArrayBuffer][], [string][], [TypedArray][] } |
-| `'module'` | Load an ES module | { [ArrayBuffer][], [string][], [TypedArray][] } |
-| `'wasm'` | Load a WebAssembly module | { [ArrayBuffer][], [string][], [TypedArray][] } |
+| `format`     | Description                        | Acceptable Types For `source` Returned by `getSource` or `transformSource` |
+| ------------ | ------------------------------     | -------------------------------------------------------------------------- |
+| `'builtin'`  | Load a Node.js builtin module      | Not applicable                                                             |
+| `'dynamic'`  | Use a [dynamic instantiate hook][] | Not applicable                                                             |
+| `'commonjs'` | Load a Node.js CommonJS module     | Not applicable                                                             |
+| `'json'`     | Load a JSON file                   | { [`string`][], [`ArrayBuffer`][], [`TypedArray`][] }                      |
+| `'module'`   | Load an ES module                  | { [`string`][], [`ArrayBuffer`][], [`TypedArray`][] }                      |
+| `'wasm'`     | Load a WebAssembly module          | { [`ArrayBuffer`][], [`TypedArray`][] }                                    |
 
 Note: These types all correspond to classes defined in ECMAScript.
 
-* The specific [ArrayBuffer][] object is a [SharedArrayBuffer][].
-* The specific [string][] object is not the class constructor, but an instance.
-* The specific [TypedArray][] object is a [Uint8Array][].
+* The specific [`ArrayBuffer`][] object is a [`SharedArrayBuffer`][].
+* 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`][].
@@ -614,11 +627,18 @@ export async function getFormat(url, context, defaultGetFormat) {
 }
 ```
 
-#### <code>getSource</code> hook
+#### `getSource(url, context, defaultGetSource)`
 
 > Note: The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
+* `url` {string}
+* `context` {Object}
+  * `format` {string}
+* `defaultGetSource` {Function}
+* Returns: {Object}
+  * `source` {string|SharedArrayBuffer|Uint8Array}
+
 The `getSource` hook provides a way to define a custom method for retrieving
 the source code of an ES module specifier. This would allow a loader to
 potentially avoid reading files from disk.
@@ -628,7 +648,7 @@ potentially avoid reading files from disk.
  * @param {string} url
  * @param {{ format: string }} context
  * @param {Function} defaultGetSource
- * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
+ * @returns {Promise<{ source: !(string | SharedArrayBuffer | Uint8Array) }>}
  */
 export async function getSource(url, context, defaultGetSource) {
   const { format } = context;
@@ -644,7 +664,7 @@ export async function getSource(url, context, defaultGetSource) {
 }
 ```
 
-#### <code>transformSource</code> hook
+#### `transformSource(source, context, defaultTransformSource)`
 
 ```console
 NODE_OPTIONS='--experimental-loader ./custom-loader.mjs' node x.js
@@ -653,6 +673,13 @@ NODE_OPTIONS='--experimental-loader ./custom-loader.mjs' node x.js
 > Note: The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
+* `source` {string|SharedArrayBuffer|Uint8Array}
+* `context` {Object}
+  * `format` {string}
+  * `url` {string}
+* Returns: {Object}
+  * `source` {string|SharedArrayBuffer|Uint8Array}
+
 The `transformSource` hook provides a way to modify the source code of a loaded
 ES module file after the source string has been loaded but before Node.js has
 done anything with it.
@@ -663,13 +690,13 @@ unknown-to-Node.js file extensions. See the [transpiler loader example][] below.
 
 ```js
 /**
- * @param {!(SharedArrayBuffer | string | Uint8Array)} source
+ * @param {!(string | SharedArrayBuffer | Uint8Array)} source
  * @param {{
- *   url: string,
  *   format: string,
+ *   url: string,
  * }} context
  * @param {Function} defaultTransformSource
- * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
+ * @returns {Promise<{ source: !(string | SharedArrayBuffer | Uint8Array) }>}
  */
 export async function transformSource(source, context, defaultTransformSource) {
   const { url, format } = context;
@@ -685,11 +712,13 @@ export async function transformSource(source, context, defaultTransformSource) {
 }
 ```
 
-#### <code>getGlobalPreloadCode</code> hook
+#### `getGlobalPreloadCode()`
 
 > Note: The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
+* 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.
@@ -726,7 +755,7 @@ const require = createRequire(process.cwd() + '/<preload>');
 To create a custom dynamic module that doesn't correspond to one of the
 existing `format` interpretations, the `dynamicInstantiate` hook can be used.
 This hook is called only for modules that return `format: 'dynamic'` from
-the [`getFormat` hook][].
+the `getFormat` hook.
 
 ```js
 /**
@@ -1254,18 +1283,17 @@ success!
 [WHATWG JSON modules specification]: https://html.spec.whatwg.org/#creating-a-json-module-script
 [`data:` URLs]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
 [`export`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/export
-[`getFormat` hook]: #esm_code_getformat_code_hook
 [`import()`]: #esm_import_expressions
 [`import.meta.url`]: #esm_import_meta
 [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
 [`module.createRequire()`]: modules.html#modules_module_createrequire_filename
 [`module.syncBuiltinESMExports()`]: modules.html#modules_module_syncbuiltinesmexports
-[`transformSource` hook]: #esm_code_transformsource_code_hook
-[ArrayBuffer]: https://www.ecma-international.org/ecma-262/6.0/#sec-arraybuffer-constructor
-[SharedArrayBuffer]: https://tc39.es/ecma262/#sec-sharedarraybuffer-constructor
-[string]: https://www.ecma-international.org/ecma-262/6.0/#sec-string-constructor
-[TypedArray]: https://www.ecma-international.org/ecma-262/6.0/#sec-typedarray-objects
-[Uint8Array]: https://www.ecma-international.org/ecma-262/6.0/#sec-uint8array
+[`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
+[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
+[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
+[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
+[`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
+[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
 [`util.TextDecoder`]: util.html#util_class_util_textdecoder
 [cjs-module-lexer]: https://github.com/guybedford/cjs-module-lexer/tree/0.4.0
 [dynamic instantiate hook]: #esm_code_dynamicinstantiate_code_hook