doc: fix links to ECMAScript module resolution
This addresses two classes of issues with a few links in the modules API documentation. The first fix is the trivial rename of a section header. The second fix involves rewriting links during the generation of the output HTML. As it is now, the links in the pseudo-code on this page take you to the Markdown source instead of the HTML page. I believe this changeset should fix that. I did my best to change as little as possible in the generated output.
Here are the changes that this makes to the generated output:
5 files changed, 18 insertions(+), 20 deletions(-)
out/doc/api/all.html | 11 +++++------
out/doc/api/all.json | 2 +-
out/doc/api/modules.html | 11 +++++------
out/doc/api/modules.json | 2 +-
out/doc/api/modules.md | 12 ++++++------
modified out/doc/api/all.html
@@ -58337,7 +58337,7 @@ MAYBE_DETECT_AND_LOAD(X)
1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
enabled, and the source code of X can be parsed as ECMAScript module using
- <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+ <a href="#all_esm_resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
the ESM resolver</a>,
a. Load X as an ECMAScript module. STOP.
3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -58399,7 +58399,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
2. If no scope was found, return.
3. If the SCOPE/package.json "imports" is null or undefined, return.
4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
- ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ ["node", "require"]) <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
5. RESOLVE_ESM_MATCH(MATCH).
LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -58410,7 +58410,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
3. Parse DIR/NAME/package.json, and look for "exports" field.
4. If "exports" is null or undefined, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
- `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ `package.json` "exports", ["node", "require"]) <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
LOAD_PACKAGE_SELF(X, DIR)
@@ -58420,15 +58420,14 @@ LOAD_PACKAGE_SELF(X, DIR)
4. If the SCOPE/package.json "name" is not the first segment of X, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
"." + X.slice("name".length), `package.json` "exports", ["node", "require"])
- <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ <a href="#all_esm_resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
RESOLVE_ESM_MATCH(MATCH)
1. let RESOLVED_PATH = fileURLToPath(MATCH)
2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
format. STOP
-3. THROW "not found"
-</pre>
+3. THROW "not found"</pre>
</section><section><h3>Caching<span><a class="mark" href="#all_modules_caching" id="all_modules_caching">#</a></span><a aria-hidden="true" class="legacy" id="modules_caching"></a></h3>
<p>Modules are cached after the first time they are loaded. This means (among other
modified out/doc/api/all.json
@@ -58013,7 +58013,7 @@
"textRaw": "All together",
"name": "All together",
"type": "misc",
- "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre>\nrequire(X) from module at path Y\n1. If X is a core module,\n a. return the core module\n b. STOP\n2. If X begins with '/'\n a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n a. LOAD_AS_FILE(Y + X)\n b. LOAD_AS_DIRECTORY(Y + X)\n c. THROW \"not found\"\n4. If X begins with '#'\n a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n enabled, and the source code of X can be parsed as ECMAScript module using\n <a href=\"esm.md#resolver-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n the ESM resolver</a>,\n a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found\n 1. MAYBE_DETECT_AND_LOAD(X.js)\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n 2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n 2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n a. Parse X/package.json, and look for \"main\" field.\n b. If \"main\" is a falsy value, GOTO 2.\n c. let M = X + (json main field)\n d. LOAD_AS_FILE(M)\n e. LOAD_INDEX(M)\n f. LOAD_INDEX(X) DEPRECATED\n g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n a. LOAD_PACKAGE_EXPORTS(X, DIR)\n b. LOAD_AS_FILE(DIR/X)\n c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n a. if PARTS[I] = \"node_modules\" CONTINUE\n b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n c. DIRS = DIR + DIRS\n d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n format. STOP\n3. THROW \"not found\"\n</pre>"
+ "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre><code class=\"language-pre\">require(X) from module at path Y\n1. If X is a core module,\n a. return the core module\n b. STOP\n2. If X begins with '/'\n a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n a. LOAD_AS_FILE(Y + X)\n b. LOAD_AS_DIRECTORY(Y + X)\n c. THROW \"not found\"\n4. If X begins with '#'\n a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n enabled, and the source code of X can be parsed as ECMAScript module using\n <a href=\"esm.html#resolution-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n the ESM resolver</a>,\n a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found\n 1. MAYBE_DETECT_AND_LOAD(X.js)\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n 2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n 2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n a. Parse X/package.json, and look for \"main\" field.\n b. If \"main\" is a falsy value, GOTO 2.\n c. let M = X + (json main field)\n d. LOAD_AS_FILE(M)\n e. LOAD_INDEX(M)\n f. LOAD_INDEX(X) DEPRECATED\n g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n a. LOAD_PACKAGE_EXPORTS(X, DIR)\n b. LOAD_AS_FILE(DIR/X)\n c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n a. if PARTS[I] = \"node_modules\" CONTINUE\n b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n c. DIRS = DIR + DIRS\n d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n [\"node\", \"require\"]) <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n format. STOP\n3. THROW \"not found\"\n</code></pre>"
},
{
"textRaw": "Caching",
modified out/doc/api/modules.html
@@ -603,7 +603,7 @@ MAYBE_DETECT_AND_LOAD(X)
1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
enabled, and the source code of X can be parsed as ECMAScript module using
- <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+ <a href="esm.html#resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
the ESM resolver</a>,
a. Load X as an ECMAScript module. STOP.
3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -665,7 +665,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
2. If no scope was found, return.
3. If the SCOPE/package.json "imports" is null or undefined, return.
4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
- ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ ["node", "require"]) <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
5. RESOLVE_ESM_MATCH(MATCH).
LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -676,7 +676,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
3. Parse DIR/NAME/package.json, and look for "exports" field.
4. If "exports" is null or undefined, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
- `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ `package.json` "exports", ["node", "require"]) <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
LOAD_PACKAGE_SELF(X, DIR)
@@ -686,15 +686,14 @@ LOAD_PACKAGE_SELF(X, DIR)
4. If the SCOPE/package.json "name" is not the first segment of X, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
"." + X.slice("name".length), `package.json` "exports", ["node", "require"])
- <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ <a href="esm.html#resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
RESOLVE_ESM_MATCH(MATCH)
1. let RESOLVED_PATH = fileURLToPath(MATCH)
2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
format. STOP
-3. THROW "not found"
-</pre>
+3. THROW "not found"</pre>
</section><section><h3>Caching<span><a class="mark" href="#caching" id="caching">#</a></span><a aria-hidden="true" class="legacy" id="modules_caching"></a></h3>
<p>Modules are cached after the first time they are loaded. This means (among other
modified out/doc/api/modules.json
@@ -32,7 +32,7 @@
"textRaw": "All together",
"name": "All together",
"type": "misc",
- "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre>\nrequire(X) from module at path Y\n1. If X is a core module,\n a. return the core module\n b. STOP\n2. If X begins with '/'\n a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n a. LOAD_AS_FILE(Y + X)\n b. LOAD_AS_DIRECTORY(Y + X)\n c. THROW \"not found\"\n4. If X begins with '#'\n a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n enabled, and the source code of X can be parsed as ECMAScript module using\n <a href=\"esm.md#resolver-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n the ESM resolver</a>,\n a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found\n 1. MAYBE_DETECT_AND_LOAD(X.js)\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n 2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n 2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n a. Parse X/package.json, and look for \"main\" field.\n b. If \"main\" is a falsy value, GOTO 2.\n c. let M = X + (json main field)\n d. LOAD_AS_FILE(M)\n e. LOAD_INDEX(M)\n f. LOAD_INDEX(X) DEPRECATED\n g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n a. LOAD_PACKAGE_EXPORTS(X, DIR)\n b. LOAD_AS_FILE(DIR/X)\n c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n a. if PARTS[I] = \"node_modules\" CONTINUE\n b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n c. DIRS = DIR + DIRS\n d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n <a href=\"esm.md#resolver-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n format. STOP\n3. THROW \"not found\"\n</pre>"
+ "desc": "<p>To get the exact filename that will be loaded when <code>require()</code> is called, use\nthe <code>require.resolve()</code> function.</p>\n<p>Putting together all of the above, here is the high-level algorithm\nin pseudocode of what <code>require()</code> does:</p>\n<pre><code class=\"language-pre\">require(X) from module at path Y\n1. If X is a core module,\n a. return the core module\n b. STOP\n2. If X begins with '/'\n a. set Y to be the file system root\n3. If X begins with './' or '/' or '../'\n a. LOAD_AS_FILE(Y + X)\n b. LOAD_AS_DIRECTORY(Y + X)\n c. THROW \"not found\"\n4. If X begins with '#'\n a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))\n5. LOAD_PACKAGE_SELF(X, dirname(Y))\n6. LOAD_NODE_MODULES(X, dirname(Y))\n7. THROW \"not found\"\n\nMAYBE_DETECT_AND_LOAD(X)\n1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.\n2. Else, if `--experimental-require-module` and `--experimental-detect-module` are\n enabled, and the source code of X can be parsed as ECMAScript module using\n <a href=\"esm.html#resolution-algorithm-specification\">DETECT_MODULE_SYNTAX defined in\n the ESM resolver</a>,\n a. Load X as an ECMAScript module. STOP.\n3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.\n\nLOAD_AS_FILE(X)\n1. If X is a file, load X as its file extension format. STOP\n2. If X.js is a file,\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found\n 1. MAYBE_DETECT_AND_LOAD(X.js)\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X.js as an ECMAScript module. STOP.\n 2. If the \"type\" field is \"commonjs\", load X.js as an CommonJS module. STOP.\n d. MAYBE_DETECT_AND_LOAD(X.js)\n3. If X.json is a file, load X.json to a JavaScript Object. STOP\n4. If X.node is a file, load X.node as binary addon. STOP\n\nLOAD_INDEX(X)\n1. If X/index.js is a file\n a. Find the closest package scope SCOPE to X.\n b. If no scope was found, load X/index.js as a CommonJS module. STOP.\n c. If the SCOPE/package.json contains \"type\" field,\n 1. If the \"type\" field is \"module\", load X/index.js as an ECMAScript module. STOP.\n 2. Else, load X/index.js as an CommonJS module. STOP.\n2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP\n3. If X/index.node is a file, load X/index.node as binary addon. STOP\n\nLOAD_AS_DIRECTORY(X)\n1. If X/package.json is a file,\n a. Parse X/package.json, and look for \"main\" field.\n b. If \"main\" is a falsy value, GOTO 2.\n c. let M = X + (json main field)\n d. LOAD_AS_FILE(M)\n e. LOAD_INDEX(M)\n f. LOAD_INDEX(X) DEPRECATED\n g. THROW \"not found\"\n2. LOAD_INDEX(X)\n\nLOAD_NODE_MODULES(X, START)\n1. let DIRS = NODE_MODULES_PATHS(START)\n2. for each DIR in DIRS:\n a. LOAD_PACKAGE_EXPORTS(X, DIR)\n b. LOAD_AS_FILE(DIR/X)\n c. LOAD_AS_DIRECTORY(DIR/X)\n\nNODE_MODULES_PATHS(START)\n1. let PARTS = path split(START)\n2. let I = count of PARTS - 1\n3. let DIRS = []\n4. while I >= 0,\n a. if PARTS[I] = \"node_modules\" CONTINUE\n b. DIR = path join(PARTS[0 .. I] + \"node_modules\")\n c. DIRS = DIR + DIRS\n d. let I = I - 1\n5. return DIRS + GLOBAL_FOLDERS\n\nLOAD_PACKAGE_IMPORTS(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"imports\" is null or undefined, return.\n4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),\n [\"node\", \"require\"]) <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n5. RESOLVE_ESM_MATCH(MATCH).\n\nLOAD_PACKAGE_EXPORTS(X, DIR)\n1. Try to interpret X as a combination of NAME and SUBPATH where the name\n may have a @scope/ prefix and the subpath begins with a slash (`/`).\n2. If X does not match this pattern or DIR/NAME/package.json is not a file,\n return.\n3. Parse DIR/NAME/package.json, and look for \"exports\" field.\n4. If \"exports\" is null or undefined, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), \".\" + SUBPATH,\n `package.json` \"exports\", [\"node\", \"require\"]) <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nLOAD_PACKAGE_SELF(X, DIR)\n1. Find the closest package scope SCOPE to DIR.\n2. If no scope was found, return.\n3. If the SCOPE/package.json \"exports\" is null or undefined, return.\n4. If the SCOPE/package.json \"name\" is not the first segment of X, return.\n5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),\n \".\" + X.slice(\"name\".length), `package.json` \"exports\", [\"node\", \"require\"])\n <a href=\"esm.html#resolution-algorithm-specification\">defined in the ESM resolver</a>.\n6. RESOLVE_ESM_MATCH(MATCH)\n\nRESOLVE_ESM_MATCH(MATCH)\n1. let RESOLVED_PATH = fileURLToPath(MATCH)\n2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension\n format. STOP\n3. THROW \"not found\"\n</code></pre>"
},
{
"textRaw": "Caching",
modified out/doc/api/modules.md
@@ -235,7 +235,7 @@ the `require.resolve()` function.
Putting together all of the above, here is the high-level algorithm
in pseudocode of what `require()` does:
-<pre>
+```pre html
require(X) from module at path Y
1. If X is a core module,
a. return the core module
@@ -256,7 +256,7 @@ MAYBE_DETECT_AND_LOAD(X)
1. If X parses as a CommonJS module, load X as a CommonJS module. STOP.
2. Else, if `--experimental-require-module` and `--experimental-detect-module` are
enabled, and the source code of X can be parsed as ECMAScript module using
- <a href="esm.md#resolver-algorithm-specification">DETECT_MODULE_SYNTAX defined in
+ <a href="esm.md#resolution-algorithm-specification">DETECT_MODULE_SYNTAX defined in
the ESM resolver</a>,
a. Load X as an ECMAScript module. STOP.
3. THROW the SyntaxError from attempting to parse X as CommonJS in 1. STOP.
@@ -318,7 +318,7 @@ LOAD_PACKAGE_IMPORTS(X, DIR)
2. If no scope was found, return.
3. If the SCOPE/package.json "imports" is null or undefined, return.
4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
- ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
5. RESOLVE_ESM_MATCH(MATCH).
LOAD_PACKAGE_EXPORTS(X, DIR)
@@ -329,7 +329,7 @@ LOAD_PACKAGE_EXPORTS(X, DIR)
3. Parse DIR/NAME/package.json, and look for "exports" field.
4. If "exports" is null or undefined, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
- `package.json` "exports", ["node", "require"]) <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ `package.json` "exports", ["node", "require"]) <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
LOAD_PACKAGE_SELF(X, DIR)
@@ -339,7 +339,7 @@ LOAD_PACKAGE_SELF(X, DIR)
4. If the SCOPE/package.json "name" is not the first segment of X, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
"." + X.slice("name".length), `package.json` "exports", ["node", "require"])
- <a href="esm.md#resolver-algorithm-specification">defined in the ESM resolver</a>.
+ <a href="esm.md#resolution-algorithm-specification">defined in the ESM resolver</a>.
6. RESOLVE_ESM_MATCH(MATCH)
RESOLVE_ESM_MATCH(MATCH)
@@ -347,7 +347,7 @@ RESOLVE_ESM_MATCH(MATCH)
2. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
format. STOP
3. THROW "not found"
-</pre>
+```
## Caching