Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit edfbee3

Browse filesBrowse files
hybristtargos
hybrist
authored and
targos
committed
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: #29327 Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com>
1 parent 0d9ae1b commit edfbee3
Copy full SHA for edfbee3

File tree

Expand file treeCollapse file tree

12 files changed

+294
-44
lines changed
Open diff view settings
Filter options
Expand file treeCollapse file tree

12 files changed

+294
-44
lines changed
Open diff view settings
Collapse file

‎doc/api/cli.md‎

Copy file name to clipboardExpand all lines: doc/api/cli.md
+9Lines changed: 9 additions & 0 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,14 @@ added: v11.8.0
196196

197197
Enable experimental diagnostic report feature.
198198

199+
### `--experimental-resolve-self`
200+
<!-- YAML
201+
added: REPLACEME
202+
-->
203+
204+
Enable experimental support for a package using `require` or `import` to load
205+
itself.
206+
199207
### `--experimental-vm-modules`
200208
<!-- YAML
201209
added: v9.6.0
@@ -1010,6 +1018,7 @@ Node.js options that are allowed are:
10101018
* `--experimental-policy`
10111019
* `--experimental-repl-await`
10121020
* `--experimental-report`
1021+
* `--experimental-resolve-self`
10131022
* `--experimental-vm-modules`
10141023
* `--experimental-wasm-modules`
10151024
* `--force-context-aware`
Collapse file

‎doc/api/esm.md‎

Copy file name to clipboardExpand all lines: doc/api/esm.md
+24-4Lines changed: 24 additions & 4 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -839,9 +839,6 @@ _isMain_ is **true** when resolving the Node.js application entry point.
839839
> 1. Let _packageSubpath_ be *undefined*.
840840
> 1. If _packageSpecifier_ is an empty string, then
841841
> 1. Throw an _Invalid Specifier_ error.
842-
> 1. If _packageSpecifier_ does not start with _"@"_, then
843-
> 1. Set _packageName_ to the substring of _packageSpecifier_ until the
844-
> first _"/"_ separator or the end of the string.
845842
> 1. Otherwise,
846843
> 1. If _packageSpecifier_ does not contain a _"/"_ separator, then
847844
> 1. Throw an _Invalid Specifier_ error.
@@ -855,7 +852,7 @@ _isMain_ is **true** when resolving the Node.js application entry point.
855852
> 1. Set _packageSubpath_ to _"."_ concatenated with the substring of
856853
> _packageSpecifier_ from the position at the length of _packageName_.
857854
> 1. If _packageSubpath_ contains any _"."_ or _".."_ segments or percent
858-
> encoded strings for _"/"_ or _"\\"_ then,
855+
> encoded strings for _"/"_ or _"\\"_, then
859856
> 1. Throw an _Invalid Specifier_ error.
860857
> 1. If _packageSubpath_ is _undefined_ and _packageName_ is a Node.js builtin
861858
> module, then
@@ -878,8 +875,31 @@ _isMain_ is **true** when resolving the Node.js application entry point.
878875
> 1. Return **PACKAGE_EXPORTS_RESOLVE**(_packageURL_,
879876
> _packageSubpath_, _pjson.exports_).
880877
> 1. Return the URL resolution of _packageSubpath_ in _packageURL_.
878+
> 1. Set _selfUrl_ to the result of
879+
> **SELF_REFERENCE_RESOLE**(_packageSpecifier_, _parentURL_).
880+
> 1. If _selfUrl_ isn't empty, return _selfUrl_.
881881
> 1. Throw a _Module Not Found_ error.
882882
883+
**SELF_REFERENCE_RESOLVE**(_specifier_, _parentURL_)
884+
885+
> 1. Let _packageURL_ be the result of **READ_PACKAGE_SCOPE**(_parentURL_).
886+
> 1. If _packageURL_ is **null**, then
887+
> 1. Return an empty result.
888+
> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_).
889+
> 1. Set _name_ to _pjson.name_.
890+
> 1. If _name_ is empty, then return an empty result.
891+
> 1. If _name_ is equal to _specifier_, then
892+
> 1. Return the result of **PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_).
893+
> 1. If _specifier_ starts with _name_ followed by "/", then
894+
> 1. Set _subpath_ to everything after the "/".
895+
> 1. If _pjson_ is not **null** and _pjson_ has an _"exports"_ key, then
896+
> 1. Let _exports_ be _pjson.exports_.
897+
> 1. If _exports_ is not **null** or **undefined**, then
898+
> 1. Return **PACKAGE_EXPORTS_RESOLVE**(_packageURL_, _subpath_,
899+
> _pjson.exports_).
900+
> 1. Return the URL resolution of _subpath_ in _packageURL_.
901+
> 1. Otherwise return an empty result.
902+
883903
**PACKAGE_MAIN_RESOLVE**(_packageURL_, _pjson_)
884904
885905
> 1. If _pjson_ is **null**, then
Collapse file

‎doc/api/modules.md‎

Copy file name to clipboardExpand all lines: doc/api/modules.md
+10-2Lines changed: 10 additions & 2 deletions
  • Display the source diff
  • Display the rich diff
Original file line numberDiff line numberDiff line change
@@ -159,8 +159,9 @@ require(X) from module at path Y
159159
3. If X begins with './' or '/' or '../'
160160
a. LOAD_AS_FILE(Y + X)
161161
b. LOAD_AS_DIRECTORY(Y + X)
162-
4. LOAD_NODE_MODULES(X, dirname(Y))
163-
5. THROW "not found"
162+
5. LOAD_NODE_MODULES(X, dirname(Y))
163+
4. LOAD_SELF_REFERENCE(X, dirname(Y))
164+
6. THROW "not found"
164165
165166
LOAD_AS_FILE(X)
166167
1. If X is a file, load X as JavaScript text. STOP
@@ -200,6 +201,13 @@ NODE_MODULES_PATHS(START)
200201
c. DIRS = DIRS + DIR
201202
d. let I = I - 1
202203
5. return DIRS
204+
205+
LOAD_SELF_REFERENCE(X, START)
206+
1. Find the closest package scope to START.
207+
2. If no scope was found, throw "not found".
208+
3. If the name in `package.json` isn't a prefix of X, throw "not found".
209+
4. Otherwise, resolve the remainder of X relative to this package as if it
210+
was loaded via `LOAD_NODE_MODULES` with a name in `package.json`.
203211
```
204212

205213
Node.js allows packages loaded via
Collapse file

‎lib/internal/modules/cjs/loader.js‎

Copy file name to clipboardExpand all lines: lib/internal/modules/cjs/loader.js
+129-37Lines changed: 129 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ const enableSourceMaps = getOptionValue('--enable-source-maps');
5858
const preserveSymlinks = getOptionValue('--preserve-symlinks');
5959
const preserveSymlinksMain = getOptionValue('--preserve-symlinks-main');
6060
const experimentalModules = getOptionValue('--experimental-modules');
61+
const experimentalSelf = getOptionValue('--experimental-resolve-self');
6162
const manifest = getOptionValue('--experimental-policy') ?
6263
require('internal/process/policy').manifest :
6364
null;
@@ -241,6 +242,7 @@ function readPackage(requestPath) {
241242
try {
242243
const parsed = JSON.parse(json);
243244
const filtered = {
245+
name: parsed.name,
244246
main: parsed.main,
245247
exports: parsed.exports,
246248
type: parsed.type
@@ -370,6 +372,125 @@ function findLongestRegisteredExtension(filename) {
370372
return '.js';
371373
}
372374

375+
function resolveBasePath(basePath, exts, isMain, trailingSlash, request) {
376+
let filename;
377+
378+
const rc = stat(basePath);
379+
if (!trailingSlash) {
380+
if (rc === 0) { // File.
381+
if (!isMain) {
382+
if (preserveSymlinks) {
383+
filename = path.resolve(basePath);
384+
} else {
385+
filename = toRealPath(basePath);
386+
}
387+
} else if (preserveSymlinksMain) {
388+
// For the main module, we use the preserveSymlinksMain flag instead
389+
// mainly for backward compatibility, as the preserveSymlinks flag
390+
// historically has not applied to the main module. Most likely this
391+
// was intended to keep .bin/ binaries working, as following those
392+
// symlinks is usually required for the imports in the corresponding
393+
// files to resolve; that said, in some use cases following symlinks
394+
// causes bigger problems which is why the preserveSymlinksMain option
395+
// is needed.
396+
filename = path.resolve(basePath);
397+
} else {
398+
filename = toRealPath(basePath);
399+
}
400+
}
401+
402+
if (!filename) {
403+
// Try it with each of the extensions
404+
if (exts === undefined)
405+
exts = Object.keys(Module._extensions);
406+
filename = tryExtensions(basePath, exts, isMain);
407+
}
408+
}
409+
410+
if (!filename && rc === 1) { // Directory.
411+
// try it with each of the extensions at "index"
412+
if (exts === undefined)
413+
exts = Object.keys(Module._extensions);
414+
filename = tryPackage(basePath, exts, isMain, request);
415+
}
416+
417+
return filename;
418+
}
419+
420+
function trySelf(paths, exts, isMain, trailingSlash, request) {
421+
if (!experimentalSelf) {
422+
return false;
423+
}
424+
425+
const { data: pkg, path: basePath } = readPackageScope(paths[0]);
426+
if (!pkg) return false;
427+
if (typeof pkg.name !== 'string') return false;
428+
429+
let expansion;
430+
if (request === pkg.name) {
431+
expansion = '';
432+
} else if (StringPrototype.startsWith(request, `${pkg.name}/`)) {
433+
expansion = StringPrototype.slice(request, pkg.name.length);
434+
} else {
435+
return false;
436+
}
437+
438+
if (exts === undefined)
439+
exts = Object.keys(Module._extensions);
440+
441+
if (expansion) {
442+
// Use exports
443+
const fromExports = applyExports(basePath, expansion);
444+
if (!fromExports) return false;
445+
return resolveBasePath(fromExports, exts, isMain, trailingSlash, request);
446+
} else {
447+
// Use main field
448+
return tryPackage(basePath, exts, isMain, request);
449+
}
450+
}
451+
452+
function applyExports(basePath, expansion) {
453+
const pkgExports = readPackageExports(basePath);
454+
const mappingKey = `.${expansion}`;
455+
456+
if (typeof pkgExports === 'object' && pkgExports !== null) {
457+
if (ObjectPrototype.hasOwnProperty(pkgExports, mappingKey)) {
458+
const mapping = pkgExports[mappingKey];
459+
return resolveExportsTarget(pathToFileURL(basePath + '/'), mapping, '',
460+
basePath, mappingKey);
461+
}
462+
463+
let dirMatch = '';
464+
for (const candidateKey of Object.keys(pkgExports)) {
465+
if (candidateKey[candidateKey.length - 1] !== '/') continue;
466+
if (candidateKey.length > dirMatch.length &&
467+
StringPrototype.startsWith(mappingKey, candidateKey)) {
468+
dirMatch = candidateKey;
469+
}
470+
}
471+
472+
if (dirMatch !== '') {
473+
const mapping = pkgExports[dirMatch];
474+
const subpath = StringPrototype.slice(mappingKey, dirMatch.length);
475+
return resolveExportsTarget(pathToFileURL(basePath + '/'), mapping,
476+
subpath, basePath, mappingKey);
477+
}
478+
}
479+
if (mappingKey === '.' && typeof pkgExports === 'string') {
480+
return resolveExportsTarget(pathToFileURL(basePath + '/'), pkgExports,
481+
'', basePath, mappingKey);
482+
}
483+
if (pkgExports != null) {
484+
// eslint-disable-next-line no-restricted-syntax
485+
const e = new Error(`Package exports for '${basePath}' do not define ` +
486+
`a '${mappingKey}' subpath`);
487+
e.code = 'MODULE_NOT_FOUND';
488+
throw e;
489+
}
490+
491+
return path.resolve(basePath, mappingKey);
492+
}
493+
373494
// This only applies to requests of a specific form:
374495
// 1. name/.*
375496
// 2. @scope/name/.*
@@ -384,43 +505,7 @@ function resolveExports(nmPath, request, absoluteRequest) {
384505
}
385506

386507
const basePath = path.resolve(nmPath, name);
387-
const pkgExports = readPackageExports(basePath);
388-
const mappingKey = `.${expansion}`;
389-
390-
if (typeof pkgExports === 'object' && pkgExports !== null) {
391-
if (ObjectPrototype.hasOwnProperty(pkgExports, mappingKey)) {
392-
const mapping = pkgExports[mappingKey];
393-
return resolveExportsTarget(pathToFileURL(basePath + '/'), mapping, '',
394-
basePath, mappingKey);
395-
}
396-
397-
let dirMatch = '';
398-
for (const candidateKey of Object.keys(pkgExports)) {
399-
if (candidateKey[candidateKey.length - 1] !== '/') continue;
400-
if (candidateKey.length > dirMatch.length &&
401-
StringPrototype.startsWith(mappingKey, candidateKey)) {
402-
dirMatch = candidateKey;
403-
}
404-
}
405-
406-
if (dirMatch !== '') {
407-
const mapping = pkgExports[dirMatch];
408-
const subpath = StringPrototype.slice(mappingKey, dirMatch.length);
409-
return resolveExportsTarget(pathToFileURL(basePath + '/'), mapping,
410-
subpath, basePath, mappingKey);
411-
}
412-
}
413-
if (mappingKey === '.' && typeof pkgExports === 'string') {
414-
return resolveExportsTarget(pathToFileURL(basePath + '/'), pkgExports,
415-
'', basePath, mappingKey);
416-
}
417-
if (pkgExports != null) {
418-
// eslint-disable-next-line no-restricted-syntax
419-
const e = new Error(`Package exports for '${basePath}' do not define ` +
420-
`a '${mappingKey}' subpath`);
421-
e.code = 'MODULE_NOT_FOUND';
422-
throw e;
423-
}
508+
return applyExports(basePath, expansion);
424509
}
425510

426511
return path.resolve(nmPath, request);
@@ -536,6 +621,13 @@ Module._findPath = function(request, paths, isMain) {
536621
return filename;
537622
}
538623
}
624+
625+
const selfFilename = trySelf(paths, exts, isMain, trailingSlash, request);
626+
if (selfFilename) {
627+
Module._pathCache[cacheKey] = selfFilename;
628+
return selfFilename;
629+
}
630+
539631
return false;
540632
};
541633

Collapse file

‎src/env.h‎

Copy file name to clipboardExpand all lines: src/env.h
+3Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,12 +93,15 @@ struct PackageConfig {
9393
enum class Exists { Yes, No };
9494
enum class IsValid { Yes, No };
9595
enum class HasMain { Yes, No };
96+
enum class HasName { Yes, No };
9697
enum PackageType : uint32_t { None = 0, CommonJS, Module };
9798

9899
const Exists exists;
99100
const IsValid is_valid;
100101
const HasMain has_main;
101102
const std::string main;
103+
const HasName has_name;
104+
const std::string name;
102105
const PackageType type;
103106

104107
v8::Global<v8::Value> exports;

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.