doc: `READ_PACKAGE_SCOPE` returns JSON not a URL

[evanw]

📗 API Reference Docs Problem

• Version: v16.11.1

• Platform: Darwin

• Subsystem: esm

Location

Resolver Algorithm Specification

Affected URL(s):

• https://nodejs.org/api/esm.html#resolution-algorithm

Description

In the resolver algorithm specification, READ_PACKAGE_SCOPE returns a parsed JSON value but is then used as a URL. Surely this is a mistake. In detail:

1. The READ_PACKAGE_JSON function either returns null, throws an error, or returns a parsed JSON value:

   READ_PACKAGE_JSON(packageURL)

   1. Let pjsonURL be the resolution of "package.json" within packageURL.
   2. If the file at pjsonURL does not exist, then
      1. Return null.
   3. If the file at packageURL does not parse as valid JSON, then
      1. Throw an Invalid Package Configuration error.
   4. Return the parsed JSON source of the file at pjsonURL.

2. The READ_PACKAGE_SCOPE function either returns null or the result of calling READ_PACKAGE_JSON, so it also returns a parsed JSON value (called pjson below):

   READ_PACKAGE_SCOPE(url)

   1. Let scopeURL be url.
   2. While scopeURL is not the file system root,
      1. Set scopeURL to the parent URL of scopeURL.
      2. If scopeURL ends in a "node_modules" path segment, return null.
      3. Let pjson be the result of READ_PACKAGE_JSON(scopeURL).
      4. If pjson is not null, then
         1. Return pjson.
   3. Return null.

3. The ESM_FORMAT function calls READ_PACKAGE_SCOPE and uses the result as a parsed JSON object (called pjson below):

   ESM_FORMAT(url)

   1. Assert: url corresponds to an existing file.
   2. Let pjson be the result of READ_PACKAGE_SCOPE(url).
   3. If url ends in ".mjs", then
      1. Return "module".
   4. If url ends in ".cjs", then
      1. Return "commonjs".
   5. If pjson?.type exists and is "module", then
      1. If url ends in ".js", then
         1. Return "module".
      2. Throw an Unsupported File Extension error.
   6. Otherwise,
      1. Throw an Unsupported File Extension error.

4. However, both PACKAGE_SELF_RESOLVE and PACKAGE_IMPORTS_RESOLVE call READ_PACKAGE_SCOPE and use the result as a URL (called packageURL below). In particular, they pass the result to READ_PACKAGE_JSON again. I assume READ_PACKAGE_JSON is not meant to be called on its own result:

   PACKAGE_SELF_RESOLVE(packageName, packageSubpath, parentURL)

   1. Let packageURL be the result of READ_PACKAGE_SCOPE(parentURL).
   2. If packageURL is null, then
      1. Return undefined.
   3. Let pjson be the result of READ_PACKAGE_JSON(packageURL).
   4. If pjson is null or if pjson.exports is null or
      undefined, then
      1. Return undefined.
   5. If pjson.name is equal to packageName, then
      1. Return the result of PACKAGE_EXPORTS_RESOLVE(packageURL,
         packageSubpath, pjson.exports, defaultConditions).
   6. Otherwise, return undefined.

   PACKAGE_IMPORTS_RESOLVE(specifier, parentURL, conditions)

   1. Assert: specifier begins with "#".
   2. If specifier is exactly equal to "#" or starts with "#/", then
      1. Throw an Invalid Module Specifier error.
   3. Let packageURL be the result of READ_PACKAGE_SCOPE(parentURL).
   4. If packageURL is not null, then
      1. Let pjson be the result of READ_PACKAGE_JSON(packageURL).
      2. If pjson.imports is a non-null Object, then
         1. Let resolved be the result of
            PACKAGE_IMPORTS_EXPORTS_RESOLVE(
            specifier, pjson.imports, packageURL, true, conditions).
         2. If resolved is not null or undefined, return resolved.
   5. Throw a Package Import Not Defined error.

If this was type checked, this would be a type error. I'm not sure what the right fix is. Maybe READ_PACKAGE_SCOPE should return a URL instead? Anyway I think the docs should be updated even if it's possible to figure out what they actually mean, because the mismatch is unnecessarily confusing.

---

• I would like to work on this issue and
  submit a pull request.

[targos]

/cc @guybedford

[guybedford]

Fix in #40592.