module: resolve self-references

Adds the ability to `import` or `require` a package from within its
own source code. This allows tests and examples to be written using
the package name, making them easier to reuse by consumers of the
package.

Assuming the `name` field in `package.json` is set to `my-pkg`, its
test could use `require('my-pkg')` or `import 'my-pkg'` even if
there's no `node_modules/my-pkg` while testing the package itself.

An important difference between this and relative specifiers like
`require('../')` is that self-references use the public interface
of the package as defined in the `exports` field while relative
specifiers don't.

This behavior is guarded by a new experimental flag
(`--experimental-resolve-self`).

PR-URL: https://github.com/nodejs/node/pull/29327
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

3 files changed, 43 insertions, 6 deletions

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 7769b02194..69e9e52a62 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -196,6 +196,14 @@ added: v11.8.0
 
 Enable experimental diagnostic report feature.
 
+### `--experimental-resolve-self`
+<!-- YAML
+added: REPLACEME
+-->
+
+Enable experimental support for a package using `require` or `import` to load
+itself.
+
 ### `--experimental-vm-modules`
 <!-- YAML
 added: v9.6.0
@@ -1010,6 +1018,7 @@ Node.js options that are allowed are:
 * `--experimental-policy`
 * `--experimental-repl-await`
 * `--experimental-report`
+* `--experimental-resolve-self`
 * `--experimental-vm-modules`
 * `--experimental-wasm-modules`
 * `--force-context-aware`
diff --git a/doc/api/esm.md b/doc/api/esm.md
index e1002f11fb..298420465b 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -839,9 +839,6 @@ _isMain_ is **true** when resolving the Node.js application entry point.
 > 1. Let _packageSubpath_ be *undefined*.
 > 1. If _packageSpecifier_ is an empty string, then
 >    1. Throw an _Invalid Specifier_ error.
-> 1. 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.
 > 1. Otherwise,
 >    1. If _packageSpecifier_ does not contain a _"/"_ separator, then
 >       1. Throw an _Invalid Specifier_ error.
@@ -855,7 +852,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
 >    1. Set _packageSubpath_ to _"."_ concatenated with the substring of
 >       _packageSpecifier_ from the position at the length of _packageName_.
 > 1. If _packageSubpath_ contains any _"."_ or _".."_ segments or percent
->    encoded strings for _"/"_ or _"\\"_ then,
+>    encoded strings for _"/"_ or _"\\"_, then
 >    1. Throw an _Invalid Specifier_ error.
 > 1. If _packageSubpath_ is _undefined_ and _packageName_ is a Node.js builtin
 >    module, then
@@ -878,8 +875,31 @@ _isMain_ is **true** when resolving the Node.js application entry point.
 >             1. Return **PACKAGE_EXPORTS_RESOLVE**(_packageURL_,
 >                _packageSubpath_, _pjson.exports_).
 >       1. Return the URL resolution of _packageSubpath_ in _packageURL_.
+> 1. Set _selfUrl_ to the result of
+>    **SELF_REFERENCE_RESOLE**(_packageSpecifier_, _parentURL_).
+> 1. If _selfUrl_ isn't empty, return _selfUrl_.
 > 1. Throw a _Module Not Found_ error.
 
+**SELF_REFERENCE_RESOLVE**(_specifier_, _parentURL_)
+
+> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_).
+> 1. If _packageURL_ is **null**, then
+>    1. Return an empty result.
+> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_).
+> 1. Set _name_ to _pjson.name_.
+> 1. If _name_ is empty, then return an empty result.
+> 1. If _name_ is equal to _specifier_, then
+>    1. Return the result of **PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_).
+> 1. If _specifier_ starts with _name_ followed by "/", then
+>    1. Set _subpath_ to everything after the "/".
+>    1. If _pjson_ is not **null** and _pjson_ has an _"exports"_ key, then
+>       1. Let _exports_ be _pjson.exports_.
+>       1. If _exports_ is not **null** or **undefined**, then
+>          1. Return **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _subpath_,
+>             _pjson.exports_).
+>    1. Return the URL resolution of _subpath_ in _packageURL_.
+> 1. Otherwise return an empty result.
+
 **PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_)
 
 > 1. If _pjson_ is **null**, then
diff --git a/doc/api/modules.md b/doc/api/modules.md
index cb14c8face..81f9d2d853 100644
--- a/doc/api/modules.md
+++ b/doc/api/modules.md
@@ -159,8 +159,9 @@ require(X) from module at path Y
 3. If X begins with './' or '/' or '../'
    a. LOAD_AS_FILE(Y + X)
    b. LOAD_AS_DIRECTORY(Y + X)
-4. LOAD_NODE_MODULES(X, dirname(Y))
-5. THROW "not found"
+5. LOAD_NODE_MODULES(X, dirname(Y))
+4. LOAD_SELF_REFERENCE(X, dirname(Y))
+6. THROW "not found"
 
 LOAD_AS_FILE(X)
 1. If X is a file, load X as JavaScript text.  STOP
@@ -200,6 +201,13 @@ NODE_MODULES_PATHS(START)
    c. DIRS = DIRS + DIR
    d. let I = I - 1
 5. return DIRS
+
+LOAD_SELF_REFERENCE(X, START)
+1. Find the closest package scope to START.
+2. If no scope was found, throw "not found".
+3. If the name in `package.json` isn't a prefix of X, throw "not found".
+4. Otherwise, resolve the remainder of X relative to this package as if it
+   was loaded via `LOAD_NODE_MODULES` with a name in `package.json`.
 ```
 
 Node.js allows packages loaded via