Documents the dependencies field as a Map<string, string>, where key is bare identifier and value is package ID

Author: arcanis

doc/api/errors.md

@@ -2505,18 +2505,18 @@ added: REPLACEME
 -->
 
 A package attempted to import another package that exists in the [package map][]
-but is not listed in its `dependencies` array.
+but is not listed in its `dependencies` object.
 
 ```mjs
-// package-map.json declares "app" with dependencies: ["utils"]
+// package-map.json declares "app" with dependencies: {"utils": "utils"}
 // but "app" tries to import "secret-lib" which exists in the map
 
 // In app/index.js
 import secret from 'secret-lib'; // Throws ERR_PACKAGE_MAP_ACCESS_DENIED
 ```
 
 To fix this error, add the required package to the importing package's
-`dependencies` array in the package map configuration file.
+`dependencies` object in the package map configuration file.
 
 <a id="ERR_PACKAGE_MAP_INVALID"></a>
 
@@ -2546,26 +2546,28 @@ Error [ERR_PACKAGE_MAP_INVALID]: Invalid package map at "./missing.json": file n
 added: REPLACEME
 -->
 
-A package's `dependencies` array in the [package map][] references a key that
-is not defined in the `packages` object.
+A package's `dependencies` object in the [package map][] references a package
+key that is not defined in the `packages` object.
 
 ```json
 {
   "packages": {
     "app": {
       "name": "app",
       "path": "./app",
-      "dependencies": ["nonexistent"]
+      "dependencies": {
+        "foo": "nonexistent"
+      }
     }
   }
 }
 ```
 
-In this example, `"nonexistent"` is referenced in `dependencies` but not
+In this example, `"nonexistent"` is referenced as a dependency target but not
 defined in `packages`, which will throw this error.
 
-To fix this error, ensure all keys referenced in `dependencies` arrays are
-defined in the `packages` object.
+To fix this error, ensure all package keys referenced in `dependencies` values
+are defined in the `packages` object.
 
 <a id="ERR_PACKAGE_PATH_NOT_EXPORTED"></a>
 

doc/api/packages.md

@@ -989,17 +989,21 @@ Each key in `packages` is a unique identifier for a package entry:
     "app": {
       "name": "my-app",
       "path": "./packages/app",
-      "dependencies": ["utils", "ui-lib"]
+      "dependencies": {
+        "@myorg/utils": "utils",
+        "@myorg/ui-lib": "ui-lib"
+      }
     },
     "utils": {
       "name": "@myorg/utils",
-      "path": "./packages/utils",
-      "dependencies": []
+      "path": "./packages/utils"
     },
     "ui-lib": {
       "name": "@myorg/ui-lib",
       "path": "./packages/ui-lib",
-      "dependencies": ["utils"]
+      "dependencies": {
+        "@myorg/utils": "utils"
+      }
     }
   }
 }
@@ -1011,8 +1015,10 @@ Each package entry has the following fields:
   the package directory.
 * `name` {string} The package name used in import specifiers. If omitted, the
   package cannot be imported by name but can still import its dependencies.
-* `dependencies` {string\[]} Array of package keys that this package is allowed
-  to import. Defaults to an empty array.
+* `dependencies` {Object} An object mapping bare specifiers to package keys.
+  Each key is the import name used in source code, and each value is the
+  corresponding package key in the `packages` object. Defaults to an empty
+  object.
 
 ### Resolution algorithm
 
@@ -1022,9 +1028,9 @@ When a bare specifier is encountered:
    if the file path is within any package's `path`.
 2. If the importing file is not within any mapped package, a
    `MODULE_NOT_FOUND` error is thrown.
-3. Node.js searches the importing package's `dependencies` array for an entry
-   whose `name` matches the specifier's package name.
-4. If found, the specifier resolves to that dependency's `path`.
+3. Node.js looks up the specifier's package name in the importing package's
+   `dependencies` object to find the corresponding package key.
+4. If found, the specifier resolves to the target package's `path`.
 5. If the package exists in the map but is not in `dependencies`, an
    [`ERR_PACKAGE_MAP_ACCESS_DENIED`][] error is thrown.
 6. If the package does not exist in the map at all, a
@@ -1046,31 +1052,34 @@ then used to resolve the final file path.
 
 ### Multiple package versions
 
-Different packages can depend on different versions of the same package by
-using distinct keys:
+Different packages can depend on different versions of the same package.
+Because `dependencies` maps bare specifiers to package keys, two packages
+can map the same specifier to different targets:
 
 ```json
 {
   "packages": {
     "app": {
       "name": "app",
       "path": "./app",
-      "dependencies": ["component-v2"]
+      "dependencies": {
+        "component": "component-v2"
+      }
     },
     "legacy": {
       "name": "legacy",
       "path": "./legacy",
-      "dependencies": ["component-v1"]
+      "dependencies": {
+        "component": "component-v1"
+      }
     },
     "component-v1": {
       "name": "component",
-      "path": "./vendor/component-1.0.0",
-      "dependencies": []
+      "path": "./vendor/component-1.0.0"
     },
     "component-v2": {
       "name": "component",
-      "path": "./vendor/component-2.0.0",
-      "dependencies": []
+      "path": "./vendor/component-2.0.0"
     }
   }
 }

lib/internal/modules/package_map.js

@@ -32,7 +32,7 @@ let emittedWarning = false;
 /**
  * @typedef {object} PackageMapEntry
  * @property {string} path - Absolute path to package on disk
- * @property {Set<string>} dependencies - Set of package keys this package can access
+ * @property {Map<string, string>} dependencies - Map from bare specifier to package key
  * @property {string|undefined} name - Package name (undefined = nameless package)
  */
 
@@ -85,7 +85,7 @@ class PackageMap {
 
       this.#packages.set(key, {
         path: absolutePath,
-        dependencies: new SafeSet(entry.dependencies ?? []),
+        dependencies: new SafeMap(ObjectEntries(entry.dependencies ?? {})),
         name: entry.name,  // Undefined for nameless packages
       });
 
@@ -166,20 +166,9 @@ class PackageMap {
     const { packageName, subpath } = parsePackageName(specifier);
     const parentEntry = this.#packages.get(parentKey);
 
-    // Find matching dependency by name
-    let targetKey = null;
-    for (const depKey of parentEntry.dependencies) {
-      const depEntry = this.#packages.get(depKey);
-      if (!depEntry) {
-        throw new ERR_PACKAGE_MAP_KEY_NOT_FOUND(depKey, this.#configPath);
-      }
-      if (depEntry.name === packageName) {
-        targetKey = depKey;
-        break;
-      }
-    }
+    const targetKey = parentEntry.dependencies.get(packageName);
 
-    if (targetKey === null) {
+    if (targetKey === undefined) {
       // Check if package exists anywhere in map but isn't accessible
       if (this.#nameToKeys.has(packageName)) {
         throw new ERR_PACKAGE_MAP_ACCESS_DENIED(
@@ -193,6 +182,10 @@ class PackageMap {
     }
 
     const targetEntry = this.#packages.get(targetKey);
+    if (!targetEntry) {
+      throw new ERR_PACKAGE_MAP_KEY_NOT_FOUND(targetKey, this.#configPath);
+    }
+
     return { packagePath: targetEntry.path, subpath };
   }
 }

test/es-module/test-esm-package-map.mjs

@@ -261,6 +261,27 @@ describe('ESM: --experimental-package-map', () => {
     });
   });
 
+  // =========== Same Request, Different Versions ===========
+
+  describe('same request resolves to different versions', () => {
+    const versionForkMap = fixtures.path('package-map/package-map-version-fork.json');
+
+    it('resolves the same bare specifier to different packages depending on the importer', async () => {
+      // app-18 and app-19 both import 'react', but the package map wires
+      // them to react@18 and react@19 respectively.
+      const { code, stdout, stderr } = await spawnPromisified(execPath, [
+        '--experimental-package-map', versionForkMap,
+        '--input-type=module',
+        '--eval',
+        `import app18 from 'app-18'; import app19 from 'app-19'; console.log(app18); console.log(app19);`,
+      ], { cwd: fixtures.path('package-map/root') });
+
+      assert.strictEqual(code, 0, stderr);
+      assert.match(stdout, /app-18 using react 18/);
+      assert.match(stdout, /app-19 using react 19/);
+    });
+  });
+
   // =========== Longest Path Wins ===========
 
   describe('longest path wins', () => {

test/fixtures/package-map/app-18/index.js

@@ -0,0 +1,2 @@
+import react from 'react';
+export default `app-18 using react ${react.version}`;

test/fixtures/package-map/app-18/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "app-18",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  }
+}

test/fixtures/package-map/app-19/index.js

@@ -0,0 +1,2 @@
+import react from 'react';
+export default `app-19 using react ${react.version}`;

test/fixtures/package-map/app-19/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "app-19",
+  "type": "module",
+  "exports": {
+    ".": "./index.js"
+  }
+}

test/fixtures/package-map/nested-project/package-map-external-deps.json

@@ -3,12 +3,12 @@
     "app": {
       "name": "app",
       "path": "./src",
-      "dependencies": ["dep-a"]
+      "dependencies": {"dep-a": "dep-a"}
     },
     "dep-a": {
       "name": "dep-a",
       "path": "../dep-a",
-      "dependencies": []
+      "dependencies": {}
     }
   }
 }

test/fixtures/package-map/package-map-longest-path.json

@@ -3,17 +3,17 @@
     "root": {
       "name": "root",
       "path": "./root",
-      "dependencies": ["inner"]
+      "dependencies": {"inner": "inner"}
     },
     "inner": {
       "name": "inner",
       "path": "./root/node_modules/inner",
-      "dependencies": ["dep-a"]
+      "dependencies": {"dep-a": "dep-a"}
     },
     "dep-a": {
       "name": "dep-a",
       "path": "./dep-a",
-      "dependencies": []
+      "dependencies": {}
     }
   }
 }