From 6c8a6ca056ccd0d47fd155c543b7c614fd7c13e4 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Wed, 20 May 2020 10:58:12 -0400 Subject: [PATCH 1/4] esm: fix annotations on getFormat hook doc snippet Prior to this commit, the type annotations on this hook 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 --- doc/api/esm.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 38885d7a0b243e..9879fe16c196d3 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1220,18 +1220,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: }, 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. From 69bc783677b631d9b409d5141bd42ecf0b15347f Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Wed, 20 May 2020 08:05:14 -0400 Subject: [PATCH 2/4] esm: fix annotations on resolve hook doc snippet Prior to this commit, the type annotations on this hook 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/?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 Co-authored-by: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com> --- doc/api/esm.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 9879fe16c196d3..3eb147c79946a4 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), + * }} 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: } + // Always return an object of the form {url: }. 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, From 7d98d054f99a06726884278787a2f55188aef5f3 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 25 May 2020 19:52:31 -0400 Subject: [PATCH 3/4] esm: fix annotations on getSource hook doc snippet Prior to this commit, the type annotations on this hook 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/?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 --- doc/api/esm.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 3eb147c79946a4..837534e7e58999 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -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: }. return { - source: '...' + source: '...', }; } // Defer to Node.js for all other URLs. From 5304a6588a9df56b0c49288d60caf9b9f96d0904 Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Tue, 26 May 2020 00:57:18 -0400 Subject: [PATCH 4/4] esm: fix annotations on transformSource hook doc snippet Prior to this commit, the type annotations on this hook 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/?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 --- doc/api/esm.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/doc/api/esm.md b/doc/api/esm.md index 837534e7e58999..b92ae3138e97a4 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -1284,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: }. return { - source: '...' + source: '...', }; } // Defer to Node.js for all other sources. - return defaultTransformSource( - source, context, defaultTransformSource); + return defaultTransformSource(source, context, defaultTransformSource); } ```