module: Refine and unify exports resolution error handling by guybedford · Pull Request #31625 · nodejs/node

guybedford · 2020-02-03T21:45:49Z

This PR includes a number of refinements to the error handling of exports resolutions in the ES module resolver:

Exports resolution error messages and codes are fully unified between the CJS and ESM resolver implementations, with the only difference that the ESM resolver errors include an imported from ... part since they don't have natural error stacks like require() does.
The MODULE_NOT_FOUND errors from "exports" resolution are split up into three separate errors: ERR_INVALID_PACKAGE_TARGET, ERR_INVALID_MODULE_SPECIFIER, and ERR_PACKAGE_PATH_NOT_EXPORTED. Previously we wanted to try to maintain unification on the MODULE_NOT_FOUND error, but we already have ERR_INVALID_PACKAGE_CONFIG and ERR_INVALID_MODULE_SPECIFIER to track, such that this unification has become restricting I think.
ERR_INVALID_PACKAGE_TARGET is thrown whenever the exports resolution value in the package.json itself is invalid. This includes values that fail validation like invalid:url or backtrack below the package boundary like ../../../outside.
ERR_INVALID_MODULE_SPECIFIER is extended to throw for cases like "exports": { "./sub/": "./sub/" } where the user attempts to require eg pkg/sub/../../../asdf or pkg/sub/node_modules/... etc. The error thus distinguishes that the fault is with the requestor, not the package.json itself.
ERR_PACKAGE_PATH_NOT_EXPORTED is thrown whenever trying to import an export from a package that is not defined. These are effectively the encapsulation errors for "exports".

The main semantic changes in this PR are then the following:

Conditional exports fallbacks (as introduced by logical conditional exports ordering in module: implement logical conditional exports ordering #31008) are then restricted only to apply to ERR_PACKAGE_PATH_NOT_EXPORTED errors, and not the other classes of errors. This much more clearly ensures that only those conditions not defined to match fall through. For a contrived example: "exports": { "node": { "node": "not:valid" }, "default": "./valid.js" } would before this PR always return the valid.js path, but after this PR always throw an ERR_INVALID_PACKAGE_TARGET error for the not:valid path. On the other hand, "exports": { "node": { "never": "./never.js" }, "default": "./valid.js" } would fall through the "never" path fine. Array fallbacks continue to fall back on the validation errors though as designed.
Whenever "exports" is set, we no longer fall back to trying the main. If there is no main defined by exports - either because there is no "." entry, or because there is no conditional resolution for the "." entry (eg "exports": { "never": "./never.js" }), the ERR_PACKAGE_PATH_NOT_EXPORTED error will immediately throw without doing any "main" or "index.js" lookups. This makes "exports" exhaustive in its definition of the package resolution, and simplifies the error handling consistency for exports in turn.

Since its original proposal, "exports" has very much turned into a full replacement for "main". Having self-resolve entirely reliant on this field being set is also in line with this. I understand (2) may be the most controversial part of this PR with the biggest user-facing consequences, so I expect we should discuss this further in the next meeting. This PR can be adjusted further based on any resolutions. The logic connects around the error handling hence the monolith here.

In addition, this PR fixes#31510 and the incorrect use of XOR instead of bit shift described in #31008 (review).

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

guybedford · 2020-02-03T22:06:56Z

//cc @nodejs/modules-active-members

Co-Authored-By: Jordan Harband <ljharb@gmail.com>

guybedford · 2020-02-08T10:21:20Z

Thanks @addaleax for the review here, would appreciate your advice re how to properly do the check handling.

guybedford · 2020-02-10T13:13:38Z

@addaleax I've added all the checks you mentioned here now. Better docs / info around how exactly to these sorts of cases properly would definitely be useful for future reference.

nodejs-github-bot · 2020-02-18T10:12:35Z

CI: https://ci.nodejs.org/job/node-test-pull-request/29200/

nodejs-github-bot · 2020-02-18T10:56:53Z

CI: https://ci.nodejs.org/job/node-test-pull-request/29201/

PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

guybedford · 2020-02-18T11:34:59Z

Landed in 58de9b4.

guybedford · 2020-02-24T11:21:03Z

The CITGM failures were tracked down to causes unrelated to this PR in nodejs/citgm#785 (comment).

PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

Refs: nodejs#31625 Refs: nodejs#32107 Refs: babel/babel#11216

codebytere · 2020-03-15T16:26:58Z

@guybedford if this is something that should be in v12.x can you please manually backport it? Feel free to swap the label with a dont-land if that's not the case.

guybedford · 2020-03-15T17:25:52Z

@codebytere thanks for letting me know about this - backport PR at #32287.

This error happens by this change in [Node,js v13.10](nodejs/node#31625) and I think we can regard this problem as the regression of this library. For the future, we should wait nodejs/node#32107 but it is still in progress. This patch will try to workaround for it. ## Reference * nodejs/node#31625 * nodejs/node#32107 * babel/babel#11216

This error happens by this change in [Node,js v13.10](nodejs/node#31625) and I think we can regard this problem as the regression of this library. For the future, we should wait nodejs/node#32107 but it is still in progress. This patch will try to workaround for it. * nodejs/node#31625 * nodejs/node#32107 * babel/babel#11216

PR-URL: nodejs#31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

Backport-PR-URL: #32610 PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. labels Feb 3, 2020

GeoffreyBooth added the esm Issues and PRs related to the ECMAScript Modules implementation. label Feb 3, 2020

guybedford added the modules-agenda Issues and PRs to discuss during the meetings of the Modules team. label Feb 3, 2020

guybedford changed the title ~~module: Refine and unify resolver error handling~~module: Refine and unify exports resolution error handlingFeb 3, 2020

module: "exports" resolution error handling refinements
888fae1

guybedford force-pushed the module-errors branch from db65846 to 888fae1Compare February 3, 2020 21:53

GeoffreyBooth reviewed Feb 3, 2020
View reviewed changes

Comment threaddoc/api/errors.md Outdated

ljharb reviewed Feb 3, 2020
View reviewed changes

guybedfordand others added 6 commits February 4, 2020 10:17

Apply suggestions from code review
e59a16e
Co-Authored-By: Jordan Harband <ljharb@gmail.com>

linting fixest status
56269a6

unabbreviate ERR_PACKAGE_PATH_NOT_EXPORTED
fb97d97

fixup json stringify
baec562

fixup circular ref
3685468

reinline sep
cac7c60

addaleax reviewed Feb 7, 2020
View reviewed changes

Comment threadsrc/env.h Outdated
Comment threadsrc/module_wrap.cc Outdated
Comment threadsrc/module_wrap.cc Outdated
Comment threadsrc/module_wrap.cc Outdated
Comment threadsrc/module_wrap.cc Outdated
Comment threadsrc/module_wrap.cc Outdated

pr feedback
61c5de0

guybedford force-pushed the module-errors branch from 7f9c775 to d2f5a07Compare February 10, 2020 13:15

fixup local checks
f6d4dac

guybedford force-pushed the module-errors branch from d2f5a07 to f6d4dacCompare February 10, 2020 13:17

mhdawson mentioned this pull request Feb 10, 2020
Node.js Foundation Modules Team Meeting 2020-02-12 nodejs/modules#483
Closed

hybrist approved these changes Feb 10, 2020
View reviewed changes

guybedford added a commit that referenced this pull request Feb 18, 2020
module: package "exports" error refinements
58de9b4
PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

guybedford closed this Feb 18, 2020

sthagen mentioned this pull request Feb 18, 2020
module: package "exports" error refinements sthagen/nodejs-node#18
Merged
4 tasks

ronag mentioned this pull request Feb 24, 2020
Failures on all platforms? nodejs/citgm#785
Closed

This comment has been minimized.
Sign in to view

codebytere pushed a commit that referenced this pull request Feb 27, 2020
module: package "exports" error refinements
bbb6cc7
PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

codebytere mentioned this pull request Feb 29, 2020
v13.10.0 proposal #32027
Merged

MylesBorins added a commit to MylesBorins/node that referenced this pull request Mar 6, 2020
module: bring back support for exports: false
b66496d
Refs: nodejs#31625 Refs: nodejs#32107 Refs: babel/babel#11216

codebytere added the backport-requested-v12.x label Mar 15, 2020

guybedford mentioned this pull request Mar 15, 2020
[12.x backport] module: package "exports" error refinements #32287
Closed
4 tasks

chappjc mentioned this pull request Mar 25, 2020
client/webserver/site: babel build error decred/dcrdex#222
Closed

tetsuharuohzeki mentioned this pull request Mar 26, 2020
Fix ERR_PACKAGE_PATH_NOT_EXPORTED error on loading option-t. option-t/option-t#602
Merged

guybedford added a commit to guybedford/node that referenced this pull request Apr 1, 2020
module: package "exports" error refinements
03a28dd
PR-URL: nodejs#31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

MylesBorins pushed a commit to MylesBorins/node that referenced this pull request Apr 3, 2020
module: package "exports" error refinements
37aee30
PR-URL: nodejs#31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

MylesBorins added backport-open-v12.x and removed backport-requested-v12.x labels Apr 3, 2020

MylesBorins pushed a commit that referenced this pull request Apr 3, 2020
module: package "exports" error refinements
c537afb
Backport-PR-URL: #32610 PR-URL: #31625 Reviewed-By: Jan Krems <jan.krems@gmail.com>

codebytere mentioned this pull request Apr 4, 2020
v12.16.2 proposal #32313
Merged

addaleax added backported-to-v12.x and removed backport-open-v12.x labels Sep 23, 2020

coderabbitaiBot mentioned this pull request Jul 24, 2026
feat(downloads): rejeicao com categoria estruturada + e-mail (spec 083) FarenRavirar/artificio#192
Merged
7 tasks

Uh oh!

Uh oh!

Conversation

guybedford commented Feb 3, 2020• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

guybedford commented Feb 3, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

guybedford commented Feb 8, 2020

Uh oh!

guybedford commented Feb 10, 2020

Uh oh!

nodejs-github-bot commented Feb 18, 2020

Uh oh!

nodejs-github-bot commented Feb 18, 2020

Uh oh!

guybedford commented Feb 18, 2020

Uh oh!

This comment has been minimized.

guybedford commented Feb 24, 2020

Uh oh!

codebytere commented Mar 15, 2020

Uh oh!

guybedford commented Mar 15, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

guybedford commented Feb 3, 2020•
edited
Loading