vm: use import attributes instead of import assertions

The old import assertions proposal has been
renamed to "import attributes" with the following major changes:

1. The keyword is now `with` instead of `assert`.
2. Unknown assertions cause an error rather than being ignored.

This PR updates the documentation to encourage folks to use the new
syntax, and add aliases to preserve backward compatibility.

PR-URL: #50141
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Vinícius Lourenço Claro Cardoso <contact@viniciusl.com.br>

doc/api/vm.md

@@ -62,7 +62,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
   - version: v10.6.0
     pr-url: https://github.com/nodejs/node/pull/20300
@@ -101,7 +101,7 @@ changes:
     using it in a production environment.
     * `specifier` {string} specifier passed to `import()`
     * `script` {vm.Script}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
@@ -615,6 +615,14 @@ The identifier of the current module, as set in the constructor.
 
 ### `module.link(linker)`
 
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/50141
+    description: The option `extra.assert` is renamed to `extra.attributes`. The
+                 former name is still provided for backward compatibility.
+-->
+
 * `linker` {Function}
   * `specifier` {string} The specifier of the requested module:
     ```mjs
@@ -625,15 +633,14 @@ The identifier of the current module, as set in the constructor.
   * `referencingModule` {vm.Module} The `Module` object `link()` is called on.
 
   * `extra` {Object}
-    * `assert` {Object} The data from the assertion:
-      <!-- eslint-skip -->
-      ```js
-      import foo from 'foo' assert { name: 'value' };
-      //                           ^^^^^^^^^^^^^^^^^ the assertion
+    * `attributes` {Object} The data from the attribute:
+      ```mjs
+      import foo from 'foo' with { name: 'value' };
+      //                         ^^^^^^^^^^^^^^^^^ the attribute
       ```
-      Per ECMA-262, hosts are expected to ignore assertions that they do not
-      support, as opposed to, for example, triggering an error if an
-      unsupported assertion is present.
+      Per ECMA-262, hosts are expected to trigger an error if an
+      unsupported attribute is present.
+    * `assert` {Object} Alias for `extra.attributes`.
 
   * Returns: {vm.Module|Promise}
 * Returns: {Promise}
@@ -732,7 +739,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
 -->
 
@@ -762,7 +769,7 @@ changes:
     `import()` will reject with [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][].
     * `specifier` {string} specifier passed to `import()`
     * `module` {vm.Module}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
@@ -977,7 +984,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
   - version: v15.9.0
     pr-url: https://github.com/nodejs/node/pull/35431
@@ -1021,7 +1028,7 @@ changes:
     considered stable.
     * `specifier` {string} specifier passed to `import()`
     * `function` {Function}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
@@ -1207,7 +1214,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
   - version: v6.3.0
     pr-url: https://github.com/nodejs/node/pull/6635
@@ -1245,7 +1252,7 @@ changes:
     using it in a production environment.
     * `specifier` {string} specifier passed to `import()`
     * `script` {vm.Script}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
@@ -1285,7 +1292,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
   - version: v14.6.0
     pr-url: https://github.com/nodejs/node/pull/34023
@@ -1344,7 +1351,7 @@ changes:
     using it in a production environment.
     * `specifier` {string} specifier passed to `import()`
     * `script` {vm.Script}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is
@@ -1388,7 +1395,7 @@ changes:
     - v17.0.0
     - v16.12.0
     pr-url: https://github.com/nodejs/node/pull/40249
-    description: Added support for import assertions to the
+    description: Added support for import attributes to the
                  `importModuleDynamically` parameter.
   - version: v6.3.0
     pr-url: https://github.com/nodejs/node/pull/6635
@@ -1424,7 +1431,7 @@ changes:
     using it in a production environment.
     * `specifier` {string} specifier passed to `import()`
     * `script` {vm.Script}
-    * `importAssertions` {Object} The `"assert"` value passed to the
+    * `importAttributes` {Object} The `"with"` value passed to the
       [`optionsExpression`][] optional parameter, or an empty object if no value
       was provided.
     * Returns: {Module Namespace Object|vm.Module} Returning a `vm.Module` is

lib/internal/vm/module.js

@@ -304,8 +304,8 @@ class SourceTextModule extends Module {
     this[kLink] = async (linker) => {
       this.#statusOverride = 'linking';
 
-      const promises = this[kWrap].link(async (identifier, assert) => {
-        const module = await linker(identifier, this, { assert });
+      const promises = this[kWrap].link(async (identifier, attributes) => {
+        const module = await linker(identifier, this, { attributes, assert: attributes });
         if (module[kWrap] === undefined) {
           throw new ERR_VM_MODULE_NOT_MODULE();
         }

test/parallel/test-vm-module-link.js

@@ -1,6 +1,6 @@
 'use strict';
 
-// Flags: --experimental-vm-modules
+// Flags: --experimental-vm-modules --harmony-import-attributes
 
 const common = require('../common');
 
@@ -126,12 +126,14 @@ async function circular2() {
 
 async function asserts() {
   const m = new SourceTextModule(`
-  import "foo" assert { n1: 'v1', n2: 'v2' };
+  import "foo" with { n1: 'v1', n2: 'v2' };
   `, { identifier: 'm' });
   await m.link((s, r, p) => {
     assert.strictEqual(s, 'foo');
     assert.strictEqual(r.identifier, 'm');
+    assert.strictEqual(p.attributes.n1, 'v1');
     assert.strictEqual(p.assert.n1, 'v1');
+    assert.strictEqual(p.attributes.n2, 'v2');
     assert.strictEqual(p.assert.n2, 'v2');
     return new SourceTextModule('');
   });