doc: document exports target fallback arrays - #65240
Open
theSnackOverflow wants to merge 1 commit into
Open
Conversation
The `"exports"` field accepts an array of targets, but the only trace of it in the documentation was the `string[]` in the field's type notation. Nothing described when Node.js moves on to the next item. Document the three cases that skip an item: unrecognized target syntax, an object whose conditions do not match, and `null`. Also state that a missing file is not one of them, since targets are matched without checking the filesystem, so an array of valid paths always resolves to the first one. The syntax case comes from review feedback left on an earlier attempt that was closed without landing: a version that predates a given target form treats that form as invalid and falls through, which is what makes these arrays useful for compatibility. Fixes: nodejs#58600 Refs: nodejs#63340 Signed-off-by: Ji Hoon Kang <ivory.ma9ic@gmail.com>
Collaborator
|
Review requested:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
"exports"accepts an array of targets, butpackages.mdnever described it.The only trace was the
string[]in the field's type notation, which is whatthe issue reports.
What this documents
A new "Target fallback arrays" section covering when Node.js skips an item and
continues with the next one:
nulland, explicitly, that a missing file is not one of them. Targets are matched
without checking the filesystem, so an array of valid paths always resolves to
the first one. That is the misconception the issue author ran into: after
noticing paths are matched regardless of whether the file exists, they asked
"what is the practical purpose of the array?" and had to find the answer outside
the Node.js documentation.
Verification
The behaviour was read off
resolvePackageTarget()inlib/internal/modules/esm/resolve.jsand cross-checked against the existingfixtures, which encode every skip case:
test/es-module/test-esm-exports.mjsexpectsnofallback1to behave as notexported and
nofallback2to be an invalid target, which is the distinction thefinal paragraph of the new section draws.
node tools/lint-md/lint-md.mjs doc/api/packages.md— cleanpython3 tools/test.py doctool— 3/3 passingRelation to earlier work
This supersedes #63340, which was closed without landing. That PR received a
review comment from @ljharb pointing out that fallback also happens when a
Node.js version cannot understand a target's syntax, so an older version skips
an object target and falls through. The comment was never addressed. It is now
the first bullet of the new section, because it is what makes fallback arrays
useful for compatibility rather than a file-existence fallback.
@Prakhar2275 expressed interest in documenting this in the issue thread but did
not open a PR. Happy to step aside if they are still working on it.