esm: fix loader hooks doc annotations

Prior to this commit, the type annotations on the ESM loader hooks
were invalid. This has been corrected and is ensured to be compatible
with both the TypeScript and Closure type systems.

Notes:
    https://www.typescriptlang.org/play/index.html?useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+kArsgDZQwIrpYDyARgFYCmAxrhTwD2RXFwAeuSAAoe1ZFxE0AnpC5p4uJQEp6cJKgyYAYpSJ8CwigBMuAM0SUauAOJdcRwcjSJcu2PNxqImwsAAVkQTQCbC4AHkxIW09vXAAuSDxCUkgyAD4yemBwcXhPSURsJTNE03NhSBI3Dy8fKWoaABpIIRFxXC6be0cXJuSfLSwoSAJbaQBZHwALADpUIitIqQncyAAGZYBWCYTgYEgAZUiubuErAlwLImWpyEhTyGaMq8hPSEQaGiQACqACUADLYAaCL5oa6yPCRSA0QQkAg8RK-GyiLzEYgkDEtXDPV6vd4AQRoAHdEEoQgEgn8iD9OLxJIJZrhFtckl4sDyUulYpk8fkupSufJIJyuC83md+T5piFhNd2VKuRl8HiQsR1ddcIg2DRrobBAA3LjEkn05BMzCy14KtKQADkaEEVkcXBdHVlZAA3FMCqSzgAROxcZBS6EAOQ9lo4IR5fwBP2lUdBEKtNqZgwcTlc7jGuDatC6PVEEgGdnzIyLhK0gbIQA
    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%2520url%250A%2520*%2520%2540param%2520%257BObject%257D%2520context%2520(currently%2520empty)%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultGetFormat%250A%2520*%2520%2540returns%2520%257BPromise%253C%257B%2520format%253A%2520string%2520%257D%253E%257D%250A%2520*%252F%250Aexport%2520async%2520function%2520getFormat(url%252C%2520context%252C%2520defaultGetFormat)%2520%257B%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%2520URLs%252C%2520do%2520some%2520custom%2520logic%2520for%2520determining%2520format.%250A%2520%2520%2520%2520%252F%252F%2520Always%2520return%2520an%2520object%2520of%2520the%2520form%2520%257Bformat%253A%2520%253Cstring%253E%257D%252C%2520where%2520the%250A%2520%2520%2520%2520%252F%252F%2520format%2520is%2520one%2520of%2520the%2520strings%2520in%2520the%2520table%2520above.%250A%2520%2520%2520%2520return%2520%257B%250A%2520%2520%2520%2520%2520%2520format%253A%2520'module'%252C%250A%2520%2520%2520%2520%257D%253B%250A%2520%2520%257D%250A%2520%2520%252F%252F%2520Defer%2520to%2520Node.js%2520for%2520all%2520other%2520URLs.%250A%2520%2520return%2520defaultGetFormat(url%252C%2520context%252C%2520defaultGetFormat)%253B%250A%257D

    https://www.typescriptlang.org/play/?useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+k28ApgMYEBmB1yUMCK6WmbkfSyakVwBVAEoAZAFyQAhAAo8hUpAA+kAK5EAJtSZFq2gJQAaXn1oB7HQVwFr2GQoCCyVAE8APEuIkAfKa8ZBRWwtQAHri8HKgYmABiWrR21hS6DIgaADa4YtTYllkAbtTRgrgayETYWAoACsiWaATY1J6YmshZMj4qZAFkbMDgEfCWyLiQiNjuRLSQDEkpRJCCBcXUijT0TCwmkKG4Ebj76Zk5eeslRlhQBw6THQJCopKQALyQRNlZkBSfh2OAG47oxIPIALKIXAACwAdKgdE15Dc-JAAAxwgCsNw6wGAkAAyk1qPcbMs4Xc+PjIPFxpQSZB6Ygsr8qHRGMxkNhTpYGWhSbQNHgmpAspYSAR5gx6WtCkVfJS+NSCc4sgB3RDuGrlSorRArSwAIwAVnRJpYGJBYaSZcg4pVupBvPhfH4yErlbqqrdlcrHTJnsJxBJIAB+Kl+r7UdWQENbDm7ZD7IOvCRGOEwwRWqSRv0GWPx9k7LkZrN6Mx+sggviDPhgyHQ+GI7TIm6eDHY3GQGnOIiWG3IMnaWz2IielWQADqMKEBxZWV8kAABmdsrl8vLqMv9japsgSBoBcIarQDZAjaS0JYR7ttHDIABJFawlqRmln1qQWwAchqiG0EcVANAdZyHIoWQ0W16TQaFaBhJdQhHZYWUgUZxlwbAJ1WagKh9NcLk3DYExLPZfSjOFKMBSJKyjJDRwcGQAG1KLhajcDY6xkLHHlIB-EDBwAWno5YfwAXVo2sjBrP47hpAARPQWGtPkADkb2oOETRqO0plZJlB0obZORYLC7m9FYCI3K5NmLEzkzJI4aMgKzLi3aTwDIIA
    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%2520parentURL%253A%2520!(string%2520%257C%2520undefined)%252C%250A%2520*%2520%2520%2520conditions%253A%2520!(Array%253Cstring%253E)%252C%250A%2520*%2520%257D%257D%2520context%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultResolve%250A%2520*%2520%2540returns%2520%257B!(Promise%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

    https://www.typescriptlang.org/play/?useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+kArsgDZQwIrpaaQBmA9smorgFyQ8hUpDIUAxhyK4ApgA9c9OElQZMAMUpFxuAlIoATGW0SUauAOIzcAZQ7VxMpbGTXqRbFgAKyDmgLYMgA8rNj2yI4CAIQAFDYAFigyBgCCyKgAngBClGxsMsiQAD6C+MQkxZAAqsS4ABxpmQCUogB8ZPTA4PLwXLiQiNgZ2uxaOnpEkCTWdg4yMdQ0ADSQktLyuCtGJmaWM+GOLZhQq1J4WOxcPP0UALyn6woA3CcEbJAxALK88QB0qEQDH4Yi1WpAAAy-ACsR0gwGAkDsaBkDwMBF0Ul+J0gcIR6i4gj8KIJiBoNGqACUADLYLYcQnI1aUPB+SA0DgkAjiS6FVxlGQAN3KkFw8RRYTmWJxOPhkBSNAA7ogMp4+e4BpMOAAjABWMh0kA471FKM43CwEoiMgEQSE5SKWty+WQ7Sl0rVyEmx2l0stkUgAHJfsGA0tsaIXjiOjKEQARYwFEX0gByHCMvx1njNAzJhpNhSq1Owbo9k22pnMVlsB3mixWa1kCi2xgre2rcyaLzIQA
    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%2520url%250A%2520*%2520%2540param%2520%257B%257B%2520format%253A%2520string%2520%257D%257D%2520context%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultGetSource%250A%2520*%2520%2540returns%2520%257BPromise%253C%257B%2520source%253A%2520!(SharedArrayBuffer%2520%257C%2520string%2520%257C%2520Uint8Array)%2520%257D%253E%257D%250A%2520*%252F%250Aexport%2520async%2520function%2520getSource(url%252C%2520context%252C%2520defaultGetSource)%2520%257B%250A%2520%2520const%2520%257B%2520format%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%2520URLs%252C%2520do%2520some%2520custom%2520logic%2520for%2520retrieving%2520the%2520source.%250A%2520%2520%2520%2520%252F%252F%2520Always%2520return%2520an%2520object%2520of%2520the%2520form%2520%257Bsource%253A%2520%253Cstring%257Cbuffer%253E%257D.%250A%2520%2520%2520%2520return%2520%257B%250A%2520%2520%2520%2520%2520%2520source%253A%2520'...'%252C%250A%2520%2520%2520%2520%257D%253B%250A%2520%2520%257D%250A%2520%2520%252F%252F%2520Defer%2520to%2520Node.js%2520for%2520all%2520other%2520URLs.%250A%2520%2520return%2520defaultGetSource(url%252C%2520context%252C%2520defaultGetSource)%253B%250A%257D

    https://www.typescriptlang.org/play/?useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwIQAoDKAFigKYAmAgsqgJ4BCArgGZMnKQA+kAzgC7IBLAHYBzTpACqw3gA4qtAJQBfHgHsGyAMYkoMBCnRZMuyKY0AbAFw9+wkQBoTppquRpEva30GjH0SEoqmqpCvCQAHrwm+qgYmABiDEKavAIhKmQkTIgM5rwAKqhC3C5u+OpaOv6wyCS8GsVYAArIqmgC3CQAPJhqGtrWeESklNSI9Mys7FzeduJSoXJjNAoBAHxKusDgEfCuvJCI3DTJkExJKWlCkPyIxaVo5f0kuNwV2vaQwaERvJ+Z2VyBSKJVcj3eJFWxlM3z4WEgFk+Dw8AUgAF4viEwpEANxQSACJiQXAAWQ8hAAdEUyG1cKs1pAAAwUgCsUMgwGAkHKaBImKEZAEqRCFPxpk5kHirjUvMg0sQ5nMkgASgAZbj-VQyvmaBh8NqQcyqEQCTRnaVoVSCpg0Oa8Qh8t7PUWmcVcijmADu424kFq9WQ1zucoARgArEgpOVE+18h5YJ2VaxdWaiDghyZsDYu13+hpYMWuxMDSAAcgpFdLfldSjxpk2bsgABEsmwblqAHJWkgUsO+0qHRVy2PsYskbg5vOByAAnJ5Qp3UFlCGvCGfb7Yv4zrJz4GLh5PSoKPFKIA
    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%257B!(SharedArrayBuffer%2520%257C%2520string%2520%257C%2520Uint8Array)%257D%2520source%250A%2520*%2520%2540param%2520%257B%257B%250A%2520*%2520%2520%2520url%253A%2520string%252C%250A%2520*%2520%2520%2520format%253A%2520string%252C%250A%2520*%2520%257D%257D%2520context%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultTransformSource%250A%2520*%2520%2540returns%2520%257BPromise%253C%257B%2520source%253A%2520!(SharedArrayBuffer%2520%257C%2520string%2520%257C%2520Uint8Array)%2520%257D%253E%257D%250A%2520*%252F%250Aexport%2520async%2520function%2520transformSource(source%252C%2520context%252C%2520defaultTransformSource)%2520%257B%250A%2520%2520const%2520%257B%2520url%252C%2520format%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%2520URLs%252C%2520do%2520some%2520custom%2520logic%2520for%2520modifying%2520the%2520source.%250A%2520%2520%2520%2520%252F%252F%2520Always%2520return%2520an%2520object%2520of%2520the%2520form%2520%257Bsource%253A%2520%253Cstring%257Cbuffer%253E%257D.%250A%2520%2520%2520%2520return%2520%257B%250A%2520%2520%2520%2520%2520%2520source%253A%2520'...'%252C%250A%2520%2520%2520%2520%257D%253B%250A%2520%2520%257D%250A%2520%2520%252F%252F%2520Defer%2520to%2520Node.js%2520for%2520all%2520other%2520sources.%250A%2520%2520return%2520defaultTransformSource(source%252C%2520context%252C%2520defaultTransformSource)%253B%250A%257D

PR-URL: https://github.com/nodejs/node/pull/33563
Co-authored-by: Geoffrey Booth <webmaster@geoffreybooth.com>
Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>

1 files changed, 34 insertions, 39 deletions

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 38885d7a0b2..b92ae3138e9 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -1160,25 +1160,26 @@ condition list **must** be passed through to the `defaultResolve` function.
 ```js
 /**
  * @param {string} specifier
- * @param {object} context
- * @param {string} context.parentURL
- * @param {string[]} context.conditions
- * @param {function} defaultResolve
- * @returns {object} response
- * @returns {string} response.url
+ * @param {{
+ *   parentURL: !(string | undefined),
+ *   conditions: !(Array<string>),
+ * }} context
+ * @param {Function} defaultResolve
+ * @returns {!(Promise<{ url: string }>)}
  */
 export async function resolve(specifier, context, defaultResolve) {
   const { parentURL = null } = context;
-  if (someCondition) {
+  if (Math.random() > 0.5) { // Some condition.
     // For some or all specifiers, do some custom logic for resolving.
-    // Always return an object of the form {url: <string>}
+    // Always return an object of the form {url: <string>}.
     return {
-      url: (parentURL) ?
-        new URL(specifier, parentURL).href : new URL(specifier).href
+      url: parentURL ?
+        new URL(specifier, parentURL).href :
+        new URL(specifier).href,
     };
   }
-  if (anotherCondition) {
-    // When calling the defaultResolve, the arguments can be modified. In this
+  if (Math.random() < 0.5) { // Another condition.
+    // When calling `defaultResolve`, the arguments can be modified. In this
     // case it's adding another value for matching conditional exports.
     return defaultResolve(specifier, {
       ...context,
@@ -1220,18 +1221,17 @@ not a string, it will be converted to a string using [`util.TextDecoder`][].
 ```js
 /**
  * @param {string} url
- * @param {object} context (currently empty)
- * @param {function} defaultGetFormat
- * @returns {object} response
- * @returns {string} response.format
+ * @param {Object} context (currently empty)
+ * @param {Function} defaultGetFormat
+ * @returns {Promise<{ format: string }>}
  */
 export async function getFormat(url, context, defaultGetFormat) {
-  if (someCondition) {
+  if (Math.random() > 0.5) { // Some condition.
     // For some or all URLs, do some custom logic for determining format.
     // Always return an object of the form {format: <string>}, where the
     // format is one of the strings in the table above.
     return {
-      format: 'module'
+      format: 'module',
     };
   }
   // Defer to Node.js for all other URLs.
@@ -1251,19 +1251,17 @@ potentially avoid reading files from disk.
 ```js
 /**
  * @param {string} url
- * @param {object} context
- * @param {string} context.format
- * @param {function} defaultGetSource
- * @returns {object} response
- * @returns {string|buffer} response.source
+ * @param {{ format: string }} context
+ * @param {Function} defaultGetSource
+ * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
  */
 export async function getSource(url, context, defaultGetSource) {
   const { format } = context;
-  if (someCondition) {
+  if (Math.random() > 0.5) { // Some condition.
     // For some or all URLs, do some custom logic for retrieving the source.
     // Always return an object of the form {source: <string|buffer>}.
     return {
-      source: '...'
+      source: '...',
     };
   }
   // Defer to Node.js for all other URLs.
@@ -1286,28 +1284,25 @@ unknown-to-Node.js file extensions. See the [transpiler loader example][] below.
 
 ```js
 /**
- * @param {string|buffer} source
- * @param {object} context
- * @param {string} context.url
- * @param {string} context.format
- * @param {function} defaultTransformSource
- * @returns {object} response
- * @returns {string|buffer} response.source
+ * @param {!(SharedArrayBuffer | string | Uint8Array)} source
+ * @param {{
+ *   url: string,
+ *   format: string,
+ * }} context
+ * @param {Function} defaultTransformSource
+ * @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
  */
-export async function transformSource(source,
-                                      context,
-                                      defaultTransformSource) {
+export async function transformSource(source, context, defaultTransformSource) {
   const { url, format } = context;
-  if (someCondition) {
+  if (Math.random() > 0.5) { // Some condition.
     // For some or all URLs, do some custom logic for modifying the source.
     // Always return an object of the form {source: <string|buffer>}.
     return {
-      source: '...'
+      source: '...',
     };
   }
   // Defer to Node.js for all other sources.
-  return defaultTransformSource(
-    source, context, defaultTransformSource);
+  return defaultTransformSource(source, context, defaultTransformSource);
 }
 ```