vm: flip Module#link's signature

The specifier parameter is deemed to be more essential than
referencingModule. Flipping the parameter order allows developers to
write simple linker functions that only take in a specifier.

PR-URL: nodejs#18471
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

doc/api/vm.md

@@ -117,7 +117,7 @@ const contextifiedSandbox = vm.createContext({ secret: 42 });
   // "foo" module every time it is called. In a full-fledged module system, a
   // cache would probably be used to avoid duplicated modules.
 
-  async function linker(referencingModule, specifier) {
+  async function linker(specifier, referencingModule) {
     if (specifier === 'foo') {
       return new vm.Module(`
         // The "secret" variable refers to the global variable we added to
@@ -319,14 +319,13 @@ can only be called once per module.
 
 Two parameters will be passed to the `linker` function:
 
-- `referencingModule` The `Module` object `link()` is called on.
 - `specifier` The specifier of the requested module:
-
   <!-- eslint-skip -->
   ```js
   import foo from 'foo';
   //              ^^^^^ the module specifier
   ```
+- `referencingModule` The `Module` object `link()` is called on.
 
 The function is expected to return a `Module` object or a `Promise` that
 eventually resolves to a `Module` object. The returned `Module` must satisfy the

lib/internal/vm/Module.js

@@ -135,7 +135,7 @@ class Module {
     const promises = [];
     wrap.link((specifier) => {
       const p = (async () => {
-        const m = await linker(this, specifier);
+        const m = await linker(specifier, this);
         if (!m || !wrapMap.has(m))
           throw new errors.Error('ERR_VM_MODULE_NOT_MODULE');
         if (m.context !== this.context)

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

@@ -109,7 +109,7 @@ async function checkModuleState() {
 
   {
     const m = new Module('import "foo";');
-    await m.link(common.mustCall(async (module, specifier) => {
+    await m.link(common.mustCall(async (specifier, module) => {
       assert.strictEqual(module, m);
       assert.strictEqual(specifier, 'foo');
       assert.strictEqual(m.linkingStatus, 'linking');

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

@@ -18,7 +18,7 @@ async function simple() {
 
   assert.deepStrictEqual(bar.dependencySpecifiers, ['foo']);
 
-  await bar.link(common.mustCall((module, specifier) => {
+  await bar.link(common.mustCall((specifier, module) => {
     assert.strictEqual(module, bar);
     assert.strictEqual(specifier, 'foo');
     return foo;
@@ -38,7 +38,7 @@ async function depth() {
       import ${parentName} from '${parentName}';
       export default ${parentName};
     `);
-    await mod.link(common.mustCall((module, specifier) => {
+    await mod.link(common.mustCall((specifier, module) => {
       assert.strictEqual(module, mod);
       assert.strictEqual(specifier, parentName);
       return parentModule;
@@ -68,10 +68,10 @@ async function circular() {
       return foo;
     }
   `);
-  await foo.link(common.mustCall(async (fooModule, fooSpecifier) => {
+  await foo.link(common.mustCall(async (fooSpecifier, fooModule) => {
     assert.strictEqual(fooModule, foo);
     assert.strictEqual(fooSpecifier, 'bar');
-    await bar.link(common.mustCall((barModule, barSpecifier) => {
+    await bar.link(common.mustCall((barSpecifier, barModule) => {
       assert.strictEqual(barModule, bar);
       assert.strictEqual(barSpecifier, 'foo');
       assert.strictEqual(foo.linkingStatus, 'linking');
@@ -111,7 +111,7 @@ async function circular2() {
   };
   const moduleMap = new Map();
   const rootModule = new Module(sourceMap.root, { url: 'vm:root' });
-  async function link(referencingModule, specifier) {
+  async function link(specifier, referencingModule) {
     if (moduleMap.has(specifier)) {
       return moduleMap.get(specifier);
     }