esm: support source phase imports for WebAssembly

PR-URL: #56919
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>

Author: Guy Bedford

doc/api/errors.md

@@ -2736,6 +2736,17 @@ The source map could not be parsed because it does not exist, or is corrupt.
 
 A file imported from a source map was not found.
 
+<aid="ERR_SOURCE_PHASE_NOT_DEFINED"></a>
+
+### `ERR_SOURCE_PHASE_NOT_DEFINED`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The provided module import does not provide a source phase imports representation for source phase
+import syntax `import source x from 'x'` or `import.source(x)`.
+
 <aid="ERR_SQLITE_ERROR"></a>
 
 ### `ERR_SQLITE_ERROR`

doc/api/esm.md

@@ -669,17 +669,19 @@ imported from the same path.
 
 > Stability: 1 - Experimental
 
-Importing WebAssembly modules is supported under the
-`--experimental-wasm-modules` flag, allowing any `.wasm` files to be
-imported as normal modules while also supporting their module imports.
+Importing both WebAssembly module instances and WebAssembly source phase
+imports are supported under the `--experimental-wasm-modules` flag.
 
-This integration is in line with the
+Both of these integrations are in line with the
 [ES Module Integration Proposal for WebAssembly][].
 
-For example, an `index.mjs` containing:
+Instance imports allow any `.wasm` files to be imported as normal modules,
+supporting their module imports in turn.
+
+For example, an `index.js` containing:
 
 ```js
-import*asMfrom'./module.wasm';
+import*asMfrom'./library.wasm';
 console.log(M);
 ```
 
@@ -689,7 +691,35 @@ executed under:
 node --experimental-wasm-modules index.mjs
 ```
 
-would provide the exports interface for the instantiation of `module.wasm`.
+would provide the exports interface for the instantiation of `library.wasm`.
+
+### Wasm Source Phase Imports
+
+<!-- YAML
+added: REPLACEME
+-->
+
+The [Source Phase Imports][] proposal allows the `import source` keyword
+combination to import a `WebAssembly.Module` object directly, instead of getting
+a module instance already instantiated with its dependencies.
+
+This is useful when needing custom instantiations for Wasm, while still
+resolving and loading it through the ES module integration.
+
+For example, to create multiple instances of a module, or to pass custom imports
+into a new instance of `library.wasm`:
+
+```js
+importsourcelibraryModulefrom'./library.wasm';
+
+constinstance1=awaitWebAssembly.instantiate(libraryModule, {
+ custom: import1,
+});
+
+constinstance2=awaitWebAssembly.instantiate(libraryModule, {
+ custom: import2,
+});
+```
 
 <i id="esm_experimental_top_level_await"></i>
 
@@ -1126,6 +1156,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
 [Loading ECMAScript modules using `require()`]: modules.md#loading-ecmascript-modules-using-require
 [Module customization hooks]: module.md#customization-hooks
 [Node.js Module Resolution And Loading Algorithm]: #resolution-algorithm-specification
+[Source Phase Imports]: https://github.com/tc39/proposal-source-phase-imports
 [Terminology]: #terminology
 [URL]: https://url.spec.whatwg.org/
 [`"exports"`]: packages.md#exports

doc/api/vm.md

@@ -1908,6 +1908,7 @@ has the following signature:
 * `importAttributes` {Object} The `"with"` value passed to the
  [`optionsExpression`][] optional parameter, or an empty object if no value was
  provided.
+* `phase` {string} The phase of the dynamic import (`"source"` or `"evaluation"`).
 * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
  recommended in order to take advantage of error tracking, and to avoid issues
  with namespaces that contain `then` function exports.

lib/internal/modules/cjs/loader.js

@@ -1508,7 +1508,7 @@ function loadESMFromCJS(mod, filename, format, source) {
 if(isMain){
 require('internal/modules/run_main').runEntryPointWithESMLoader((cascadedLoader)=>{
 constmainURL=pathToFileURL(filename).href;
-returncascadedLoader.import(mainURL,undefined,{__proto__: null},true);
+returncascadedLoader.import(mainURL,undefined,{__proto__: null},undefined,true);
 });
 // ESM won't be accessible via process.mainModule.
 setOwnProperty(process,'mainModule',undefined);

lib/internal/modules/esm/loader.js

@@ -38,7 +38,7 @@ const {
  forceDefaultLoader,
 }=require('internal/modules/esm/utils');
 const{ kImplicitTypeAttribute }=require('internal/modules/esm/assert');
-const{ ModuleWrap, kEvaluating, kEvaluated }=internalBinding('module_wrap');
+const{ ModuleWrap, kEvaluating, kEvaluated, kEvaluationPhase, kSourcePhase}=internalBinding('module_wrap');
 const{
  urlToFilename,
 }=require('internal/modules/helpers');
@@ -236,8 +236,7 @@ class ModuleLoader {
 asyncexecuteModuleJob(url,wrap,isEntryPoint=false){
 const{ ModuleJob }=require('internal/modules/esm/module_job');
 constmodule=awaitonImport.tracePromise(async()=>{
-constjob=newModuleJob(
-this,url,undefined,wrap,false,false);
+constjob=newModuleJob(this,url,undefined,wrap,kEvaluationPhase,false,false);
 this.loadCache.set(url,undefined,job);
 const{ module }=awaitjob.run(isEntryPoint);
 returnmodule;
@@ -273,11 +272,12 @@ class ModuleLoader {
  * @param {string} [parentURL] The URL of the module where the module request is initiated.
  * It's undefined if it's from the root module.
  * @param {ImportAttributes} importAttributes Attributes from the import statement or expression.
+ * @param {number} phase Import phase.
  * @returns {Promise<ModuleJobBase>}
  */
-asyncgetModuleJobForImport(specifier,parentURL,importAttributes){
+asyncgetModuleJobForImport(specifier,parentURL,importAttributes,phase){
 constresolveResult=awaitthis.resolve(specifier,parentURL,importAttributes);
-returnthis.#getJobFromResolveResult(resolveResult,parentURL,importAttributes,false);
+returnthis.#getJobFromResolveResult(resolveResult,parentURL,importAttributes,phase,false);
 }
 
 /**
@@ -287,11 +287,12 @@ class ModuleLoader {
  * @param {string} specifier See {@link getModuleJobForImport}
  * @param {string} [parentURL] See {@link getModuleJobForImport}
  * @param {ImportAttributes} importAttributes See {@link getModuleJobForImport}
+ * @param {number} phase Import phase.
  * @returns {Promise<ModuleJobBase>}
  */
-getModuleJobForRequireInImportedCJS(specifier,parentURL,importAttributes){
+getModuleJobForRequireInImportedCJS(specifier,parentURL,importAttributes,phase){
 constresolveResult=this.resolveSync(specifier,parentURL,importAttributes);
-returnthis.#getJobFromResolveResult(resolveResult,parentURL,importAttributes,true);
+returnthis.#getJobFromResolveResult(resolveResult,parentURL,importAttributes,phase,true);
 }
 
 /**
@@ -300,16 +301,21 @@ class ModuleLoader {
  * @param {{ format: string, url: string }} resolveResult Resolved module request.
  * @param {string} [parentURL] See {@link getModuleJobForImport}
  * @param {ImportAttributes} importAttributes See {@link getModuleJobForImport}
+ * @param {number} phase Import phase.
  * @param {boolean} isForRequireInImportedCJS Whether this is done for require() in imported CJS.
  * @returns {ModuleJobBase}
  */
- #getJobFromResolveResult(resolveResult,parentURL,importAttributes,isForRequireInImportedCJS=false){
+ #getJobFromResolveResult(resolveResult,parentURL,importAttributes,phase,
+isForRequireInImportedCJS=false){
 const{ url, format }=resolveResult;
 constresolvedImportAttributes=resolveResult.importAttributes??importAttributes;
 letjob=this.loadCache.get(url,resolvedImportAttributes.type);
 
 if(job===undefined){
-job=this.#createModuleJob(url,resolvedImportAttributes,parentURL,format,isForRequireInImportedCJS);
+job=this.#createModuleJob(url,resolvedImportAttributes,phase,parentURL,format,
+isForRequireInImportedCJS);
+}else{
+job.ensurePhase(phase);
 }
 
 returnjob;
@@ -377,7 +383,7 @@ class ModuleLoader {
 constinspectBrk=(isMain&&getOptionValue('--inspect-brk'));
 
 const{ ModuleJobSync }=require('internal/modules/esm/module_job');
-job=newModuleJobSync(this,url,kEmptyObject,wrap,isMain,inspectBrk);
+job=newModuleJobSync(this,url,kEmptyObject,wrap,kEvaluationPhase,isMain,inspectBrk);
 this.loadCache.set(url,kImplicitTypeAttribute,job);
 mod[kRequiredModuleSymbol]=job.module;
 return{wrap: job.module,namespace: job.runSync(parent).namespace};
@@ -389,9 +395,10 @@ class ModuleLoader {
  * @param {string} specifier Specifier of the the imported module.
  * @param {string} parentURL Where the import comes from.
  * @param {object} importAttributes import attributes from the import statement.
+ * @param {number} phase The import phase.
  * @returns {ModuleJobBase}
  */
-getModuleJobForRequire(specifier,parentURL,importAttributes){
+getModuleJobForRequire(specifier,parentURL,importAttributes,phase){
 constparsed=URLParse(specifier);
 if(parsed!=null){
 constprotocol=parsed.protocol;
@@ -422,6 +429,7 @@ class ModuleLoader {
 }
 thrownewERR_REQUIRE_CYCLE_MODULE(message);
 }
+job.ensurePhase(phase);
 // Otherwise the module could be imported before but the evaluation may be already
 // completed (e.g. the require call is lazy) so it's okay. We will return the
 // module now and check asynchronicity of the entire graph later, after the
@@ -463,7 +471,7 @@ class ModuleLoader {
 
 constinspectBrk=(isMain&&getOptionValue('--inspect-brk'));
 const{ ModuleJobSync }=require('internal/modules/esm/module_job');
-job=newModuleJobSync(this,url,importAttributes,wrap,isMain,inspectBrk);
+job=newModuleJobSync(this,url,importAttributes,wrap,phase,isMain,inspectBrk);
 
 this.loadCache.set(url,importAttributes.type,job);
 returnjob;
@@ -543,13 +551,14 @@ class ModuleLoader {
  * by the time this returns. Otherwise it may still have pending module requests.
  * @param {string} url The URL that was resolved for this module.
  * @param {ImportAttributes} importAttributes See {@link getModuleJobForImport}
+ * @param {number} phase Import phase.
  * @param {string} [parentURL] See {@link getModuleJobForImport}
  * @param {string} [format] The format hint possibly returned by the `resolve` hook
  * @param {boolean} isForRequireInImportedCJS Whether this module job is created for require()
  * in imported CJS.
  * @returns {ModuleJobBase} The (possibly pending) module job
  */
- #createModuleJob(url,importAttributes,parentURL,format,isForRequireInImportedCJS){
+ #createModuleJob(url,importAttributes,phase,parentURL,format,isForRequireInImportedCJS){
 constcontext={ format, importAttributes };
 
 constisMain=parentURL===undefined;
@@ -575,6 +584,7 @@ class ModuleLoader {
 url,
 importAttributes,
 moduleOrModulePromise,
+phase,
 isMain,
 inspectBrk,
 isForRequireInImportedCJS,
@@ -592,11 +602,18 @@ class ModuleLoader {
  * @param {string} parentURL Path of the parent importing the module.
  * @param {Record<string, string>} importAttributes Validations for the
  * module import.
+ * @param {number} [phase] The phase of the import.
+ * @param {boolean} [isEntryPoint] Whether this is the realm-level entry point.
  * @returns {Promise<ModuleExports>}
  */
-asyncimport(specifier,parentURL,importAttributes,isEntryPoint=false){
+asyncimport(specifier,parentURL,importAttributes,phase=kEvaluationPhase,isEntryPoint=false){
 returnonImport.tracePromise(async()=>{
-constmoduleJob=awaitthis.getModuleJobForImport(specifier,parentURL,importAttributes);
+constmoduleJob=awaitthis.getModuleJobForImport(specifier,parentURL,importAttributes,
+phase);
+if(phase===kSourcePhase){
+constmodule=awaitmoduleJob.modulePromise;
+returnmodule.getModuleSourceObject();
+}
 const{ module }=awaitmoduleJob.run(isEntryPoint);
 returnmodule.getNamespace();
 },{