Resolution algorithm#

Features#

The resolver has the following properties:

• FileURL-based resolution as is used by ES modules
• Support for builtin module loading
• Relative and absolute URL resolution
• No default extensions
• No folder mains
• Bare specifier package resolution lookup through node_modules

Resolver algorithm#

The algorithm to load an ES module specifier is given through the ESM_RESOLVE method below. It returns the resolved URL for a module specifier relative to a parentURL.

The algorithm to determine the module format of a resolved URL is provided by ESM_FORMAT, which returns the unique module format for any file. The "module" format is returned for an ECMAScript Module, while the "commonjs" format is used to indicate loading through the legacy CommonJS loader. Additional formats such as "addon" can be extended in future updates.

In the following algorithms, all subroutine errors are propagated as errors of these top-level routines unless stated otherwise.

defaultConditions is the conditional environment name array, ["node", "import"].

The resolver can throw the following errors:

• Invalid Module Specifier: Module specifier is an invalid URL, package name or package subpath specifier.
• Invalid Package Configuration: package.json configuration is invalid or contains an invalid configuration.
• Invalid Package Target: Package exports or imports define a target module for the package that is an invalid type or string target.
• Package Path Not Exported: Package exports do not define or permit a target subpath in the package for the given module.
• Package Import Not Defined: Package imports do not define the specifier.
• Module Not Found: The package or module requested does not exist.
• Unsupported Directory Import: The resolved path corresponds to a directory, which is not a supported target for module imports.

Resolver Algorithm Specification#

ESM_RESOLVE(specifier, parentURL)

1. Let resolved be undefined.
2. If specifier is a valid URL, then
   1. Set resolved to the result of parsing and reserializing specifier as a URL.
3. Otherwise, if specifier starts with "/", "./", or "../", then
   1. Set resolved to the URL resolution of specifier relative to parentURL.
4. Otherwise, if specifier starts with "#", then
   1. Set resolved to the result of PACKAGE_IMPORTS_RESOLVE(specifier, parentURL, defaultConditions).
5. Otherwise,
   1. Note: specifier is now a bare specifier.
   2. Set resolved the result of PACKAGE_RESOLVE(specifier, parentURL).
6. Let format be undefined.
7. If resolved is a "file:" URL, then
   1. If resolved contains any percent encodings of "/" or "\" ("%2F" and "%5C" respectively), then
      1. Throw an Invalid Module Specifier error.
   2. If the file at resolved is a directory, then
      1. Throw an Unsupported Directory Import error.
   3. If the file at resolved does not exist, then
      1. Throw a Module Not Found error.
   4. Set resolved to the real path of resolved, maintaining the same URL querystring and fragment components.
   5. Set format to the result of ESM_FILE_FORMAT(resolved).
8. Otherwise,
   1. Set format the module format of the content type associated with the URL resolved.
9. Load resolved as module format, format.

PACKAGE_RESOLVE(packageSpecifier, parentURL)

1. Let packageName be undefined.
2. If packageSpecifier is an empty string, then
   1. Throw an Invalid Module Specifier error.
3. If packageSpecifier is a Node.js builtin module name, then
   1. Return the string "node:" concatenated with packageSpecifier.
4. If packageSpecifier does not start with "@", then
   1. Set packageName to the substring of packageSpecifier until the first "/" separator or the end of the string.
5. Otherwise,
   1. If packageSpecifier does not contain a "/" separator, then
      1. Throw an Invalid Module Specifier error.
   2. Set packageName to the substring of packageSpecifier until the second "/" separator or the end of the string.
6. If packageName starts with "." or contains "\" or "%", then
   1. Throw an Invalid Module Specifier error.
7. Let packageSubpath be "." concatenated with the substring of packageSpecifier from the position at the length of packageName.
8. If packageSubpath ends in "/", then
   1. Throw an Invalid Module Specifier error.
9. Let selfUrl be the result of PACKAGE_SELF_RESOLVE(packageName, packageSubpath, parentURL).
10. If selfUrl is not undefined, return selfUrl.
11. While parentURL is not the file system root,
12. Let packageURL be the URL resolution of "node_modules/" concatenated with packageSpecifier, relative to parentURL.
13. Set parentURL to the parent folder URL of parentURL.
14. If the folder at packageURL does not exist, then
    1. Continue the next loop iteration.
15. Let pjson be the result of READ_PACKAGE_JSON(packageURL).
16. If pjson is not null and pjson.exports is not null or undefined, then
    1. Return the result of PACKAGE_EXPORTS_RESOLVE(packageURL, packageSubpath, pjson.exports, defaultConditions).
17. Otherwise, if packageSubpath is equal to ".", then
    1. If pjson.main is a string, then
       1. Return the URL resolution of main in packageURL.
18. Otherwise,
    1. Return the URL resolution of packageSubpath in packageURL.
19. Throw a Module Not Found error.

PACKAGE_SELF_RESOLVE(packageName, packageSubpath, parentURL)

1. Let packageURL be the result of LOOKUP_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_EXPORTS_RESOLVE(packageURL, subpath, exports, conditions)

1. If exports is an Object with both a key starting with "." and a key not starting with ".", throw an Invalid Package Configuration error.
2. If subpath is equal to ".", then
   1. Let mainExport be undefined.
   2. If exports is a String or Array, or an Object containing no keys starting with ".", then
      1. Set mainExport to exports.
   3. Otherwise if exports is an Object containing a "." property, then
      1. Set mainExport to exports["."].
   4. If mainExport is not undefined, then
      1. Let resolved be the result of PACKAGE_TARGET_RESOLVE( packageURL, mainExport, null, false, conditions).
      2. If resolved is not null or undefined, return resolved.
3. Otherwise, if exports is an Object and all keys of exports start with ".", then
   1. Let matchKey be the string "./" concatenated with subpath.
   2. Let resolved be the result of PACKAGE_IMPORTS_EXPORTS_RESOLVE( matchKey, exports, packageURL, false, conditions).
   3. If resolved is not null or undefined, return resolved.
4. Throw a Package Path Not Exported error.

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 LOOKUP_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.

PACKAGE_IMPORTS_EXPORTS_RESOLVE(matchKey, matchObj, packageURL, isImports, conditions)

1. If matchKey is a key of matchObj and does not contain "*", then
   1. Let target be the value of matchObj[matchKey].
   2. Return the result of PACKAGE_TARGET_RESOLVE(packageURL, target, null, isImports, conditions).
2. Let expansionKeys be the list of keys of matchObj containing only a single "*", sorted by the sorting function PATTERN_KEY_COMPARE which orders in descending order of specificity.
3. For each key expansionKey in expansionKeys, do
   1. Let patternBase be the substring of expansionKey up to but excluding the first "*" character.
   2. If matchKey starts with but is not equal to patternBase, then
      1. Let patternTrailer be the substring of expansionKey from the index after the first "*" character.
      2. If patternTrailer has zero length, or if matchKey ends with patternTrailer and the length of matchKey is greater than or equal to the length of expansionKey, then
         1. Let target be the value of matchObj[expansionKey].
         2. Let patternMatch be the substring of matchKey starting at the index of the length of patternBase up to the length of matchKey minus the length of patternTrailer.
         3. Return the result of PACKAGE_TARGET_RESOLVE(packageURL, target, patternMatch, isImports, conditions).
4. Return null.

PATTERN_KEY_COMPARE(keyA, keyB)

1. Assert: keyA ends with "/" or contains only a single "*".
2. Assert: keyB ends with "/" or contains only a single "*".
3. Let baseLengthA be the index of "*" in keyA plus one, if keyA contains "*", or the length of keyA otherwise.
4. Let baseLengthB be the index of "*" in keyB plus one, if keyB contains "*", or the length of keyB otherwise.
5. If baseLengthA is greater than baseLengthB, return -1.
6. If baseLengthB is greater than baseLengthA, return 1.
7. If keyA does not contain "*", return 1.
8. If keyB does not contain "*", return -1.
9. If the length of keyA is greater than the length of keyB, return -1.
10. If the length of keyB is greater than the length of keyA, return 1.
11. Return 0.

PACKAGE_TARGET_RESOLVE(packageURL, target, patternMatch, isImports, conditions)

1. If target is a String, then
   1. If target does not start with "./", then
      1. If isImports is false, or if target starts with "../" or "/", or if target is a valid URL, then
         1. Throw an Invalid Package Target error.
      2. If patternMatch is a String, then
         1. Return PACKAGE_RESOLVE(target with every instance of "*" replaced by patternMatch, packageURL + "/").
      3. Return PACKAGE_RESOLVE(target, packageURL + "/").
   2. If target split on "/" or "\" contains any "", ".", "..", or "node_modules" segments after the first "." segment, case insensitive and including percent encoded variants, throw an Invalid Package Target error.
   3. Let resolvedTarget be the URL resolution of the concatenation of packageURL and target.
   4. Assert: resolvedTarget is contained in packageURL.
   5. If patternMatch is null, then
      1. Return resolvedTarget.
   6. If patternMatch split on "/" or "\" contains any "", ".", "..", or "node_modules" segments, case insensitive and including percent encoded variants, throw an Invalid Module Specifier error.
   7. Return the URL resolution of resolvedTarget with every instance of "*" replaced with patternMatch.
2. Otherwise, if target is a non-null Object, then
   1. If exports contains any index property keys, as defined in ECMA-262 6.1.7 Array Index, throw an Invalid Package Configuration error.
   2. For each property p of target, in object insertion order as,
      1. If p equals "default" or conditions contains an entry for p, then
         1. Let targetValue be the value of the p property in target.
         2. Let resolved be the result of PACKAGE_TARGET_RESOLVE( packageURL, targetValue, patternMatch, isImports, conditions).
         3. If resolved is equal to undefined, continue the loop.
         4. Return resolved.
   3. Return undefined.
3. Otherwise, if target is an Array, then
   1. If _target.length is zero, return null.
   2. For each item targetValue in target, do
      1. Let resolved be the result of PACKAGE_TARGET_RESOLVE( packageURL, targetValue, patternMatch, isImports, conditions), continuing the loop on any Invalid Package Target error.
      2. If resolved is undefined, continue the loop.
      3. Return resolved.
   3. Return or throw the last fallback resolution null return or error.
4. Otherwise, if target is null, return null.
5. Otherwise throw an Invalid Package Target error.

ESM_FILE_FORMAT(url)

1. Assert: url corresponds to an existing file.
2. If url ends in ".mjs", then
   1. Return "module".
3. If url ends in ".cjs", then
   1. Return "commonjs".
4. If url ends in ".json", then
   1. Return "json".
5. Let packageURL be the result of LOOKUP_PACKAGE_SCOPE(url).
6. Let pjson be the result of READ_PACKAGE_JSON(packageURL).
7. 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.
8. Otherwise,
   1. Throw an Unsupported File Extension error.

LOOKUP_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 pjsonURL be the resolution of "package.json" within scopeURL.
   4. if the file at pjsonURL exists, then
      1. Return scopeURL.
3. Return null.

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.

Customizing ESM specifier resolution algorithm#

The Loaders API provides a mechanism for customizing the ESM specifier resolution algorithm. An example loader that provides CommonJS-style resolution for ESM specifiers is commonjs-extension-resolution-loader.