module: exports pattern support

PR-URL: #34718 Backport-PR-URL: #35385 Reviewed-By: Jan Krems <[email protected]> Reviewed-By: Matteo Collina <[email protected]>

Author: guybedford

doc/api/esm.md

@@ -298,14 +298,14 @@ package. It is not a strong encapsulation since a direct require of any
 absolute subpath of the package such as
 `require('/path/to/node_modules/pkg/subpath.js')` will still load `subpath.js`.
 
-####Subpath exports
+### Subpath exports
 
-When using the `"exports"` field, custom subpaths can be defined along
-with the main entry point by treating the main entry point as the
-`"."` subpath:
+> Stability: 1 - Experimental
 
-<!-- eslint-skip -->
-```js
+When using the `"exports"` field, custom subpaths can be defined along with the
+main entry point by treating the main entry point as the `"."` subpath:
+
+```json
 {
 "main": "./main.js",
 "exports":{
@@ -315,8 +315,7 @@ with the main entry point by treating the main entry point as the
 }
 ```
 
-Now only the defined subpath in `"exports"` can be imported by a
-consumer:
+Now only the defined subpath in `"exports"` can be imported by a consumer:
 
 ```js
 importsubmodulefrom'es-module-package/submodule';
@@ -330,30 +329,46 @@ import submodule from 'es-module-package/private-module.js'
 // Throws ERR_PACKAGE_PATH_NOT_EXPORTED
 ```
 
-Entire folders can also be mapped with package exports:
+### Subpath export patterns
 
-<!-- eslint-skip -->
-```js
+> Stability: 1 - Experimental
+
+Explicitly listing each exports subpath entry is recommended for packages with
+a small number of exports. But for packages that have very large numbers of
+subpaths this can start to cause package.json bloat and maintenance issues.
+
+For these use cases, subpath export patterns can be used instead:
+
+```json
 // ./node_modules/es-module-package/package.json
 {
 "exports":{
-"./features/":"./src/features/"
+"./features/*": "./src/features/*.js"
  }
 }
 ```
 
-With the above, all modules within the `./src/features/` folder
-are exposed deeply to `import` and `require`:
+The left hand matching pattern must always end in `*`. All instances of `*` on
+the right hand side will then be replaced with this value, including if it
+contains any `/` separators.
 
 ```js
-importfeaturefrom'es-module-package/features/x.js';
+importfeatureXfrom'es-module-package/features/x';
 // Loads ./node_modules/es-module-package/src/features/x.js
+
+importfeatureYfrom'es-module-package/features/y/y';
+// Loads ./node_modules/es-module-package/src/features/y/y.js
 ```
 
-When using folder mappings, ensure that you do want to expose every
-module inside the subfolder. Any modules which are not public
-should be moved to another folder to retain the encapsulation
-benefits of exports.
+This is a direct static replacement without any special handling for file
+extensions. In the previous example, `pkg/features/x.json` would be resolved to
+`./src/features/x.json.js` in the mapping.
+
+The property of exports being statically enumerable is maintained with exports
+patterns since the individual exports for a package can be determined by
+treating the right hand side target pattern as a `**` glob against the list of
+files within the package. Because `node_modules` paths are forbidden in exports
+targets, this expansion is dependent on only the files of the package itself.
 
 #### Package exports fallbacks
 
@@ -1741,7 +1756,8 @@ The resolver can throw the following errors:
 >1.Set_mainExport_to_exports_\[_"."_\].
 >1.If_mainExport_isnot**undefined**, then
 >1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
-> _packageURL_, _mainExport_, _""_, **false**, _conditions_).
+> _packageURL_, _mainExport_, _""_, **false**, **false**,
+> _conditions_).
 >1.If_resolved_isnot**null**or**undefined**, then
 >1.Return_resolved_.
 >1.Otherwise, if_exports_isanObjectandallkeysof_exports_startwith
@@ -1775,29 +1791,43 @@ _isImports_, _conditions_)
 >1.If_matchKey_isakeyof_matchObj_, anddoesnotendin_"*"_, then
 >1.Let_target_bethevalueof_matchObj_\[_matchKey_\].
 >1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
-> _packageURL_, _target_, _""_, _isImports_, _conditions_).
+> _packageURL_, _target_, _""_, **false**, _isImports_, _conditions_).
 >1.Returntheobject_{resolved, exact:**true** }_.
->1.Let_expansionKeys_bethelistofkeysof_matchObj_endingin_"/"_,
->sortedbylengthdescending.
+>1.Let_expansionKeys_bethelistofkeysof_matchObj_endingin_"/"_
+>or_"*"_, sortedbylengthdescending.
 >1.Foreachkey_expansionKey_in_expansionKeys_, do
+>1.If_expansionKey_endsin_"*"_and_matchKey_startswithbutis
+>notequaltothesubstringof_expansionKey_excludingthelast_"*"_
+>character, then
+>1.Let_target_bethevalueof_matchObj_\[_expansionKey_\].
+>1.Let_subpath_bethesubstringof_matchKey_startingatthe
+>indexofthelengthof_expansionKey_minusone.
+>1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
+> _packageURL_, _target_, _subpath_, **true**, _isImports_,
+> _conditions_).
+>1.Returntheobject_{resolved, exact:**true** }_.
 >1.If_matchKey_startswith_expansionKey_, then
 >1.Let_target_bethevalueof_matchObj_\[_expansionKey_\].
 >1.Let_subpath_bethesubstringof_matchKey_startingatthe
 >indexofthelengthof_expansionKey_.
 >1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
-> _packageURL_, _target_, _subpath_, _isImports_, _conditions_).
+> _packageURL_, _target_, _subpath_, **false**, _isImports_,
+> _conditions_).
 >1.Returntheobject_{resolved, exact:**false** }_.
 >1.Returntheobject_{resolved:**null**, exact:**true** }_.
 
-**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _internal_,
-_conditions_)
+**PACKAGE_TARGET_RESOLVE**(_packageURL_, _target_, _subpath_, _pattern_,
+_internal_, _conditions_)
 
 >1.If_target_isaString, then
->1.If_subpath_hasnon-zerolengthand_target_doesnotendwith_"/"_,
->throwan_InvalidModuleSpecifier_error.
+>1.If_pattern_is**false**, _subpath_hasnon-zerolengthand_target_
+>doesnotendwith_"/"_, throwan_InvalidModuleSpecifier_error.
 >1.If_target_doesnotstartwith_"./"_, then
 >1.If_internal_is**true**and_target_doesnotstartwith_"../"_or
 >_"/"_andisnotavalidURL, then
+>1.If_pattern_is**true**, then
+>1.Return**PACKAGE_RESOLVE**(_target_ with every instance of
+> _"*"_ replaced by _subpath_, _packageURL_ + _"/"_)_.
 >1.Return**PACKAGE_RESOLVE**(_target_ + _subpath_,
 > _packageURL_ + _"/"_)_.
 >1.Otherwise, throwan_InvalidPackageTarget_error.
@@ -1809,8 +1839,12 @@ _conditions_)
 >1.Assert:_resolvedTarget_iscontainedin_packageURL_.
 >1.If_subpath_spliton_"/"_or_"\\"_containsany_"."_, _".."_or
 >_"node_modules"_segments, throwan_InvalidModuleSpecifier_error.
->1.ReturntheURLresolutionoftheconcatenationof_subpath_and
->_resolvedTarget_.
+>1.If_pattern_is**true**, then
+>1.ReturntheURLresolutionof_resolvedTarget_witheveryinstanceof
+>_"*"_replacedwith_subpath_.
+>1.Otherwise,
+>1.ReturntheURLresolutionoftheconcatenationof_subpath_and
+>_resolvedTarget_.
 >1.Otherwise, if_target_isanon-nullObject, then
 >1.If_exports_containsanyindexpropertykeys, asdefinedinECMA-262
 > [6.1.7ArrayIndex][], throwan_InvalidPackageConfiguration_error.
@@ -1819,16 +1853,18 @@ _conditions_)
 >then
 >1.Let_targetValue_bethevalueofthe_p_propertyin_target_.
 >1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
-> _packageURL_, _targetValue_, _subpath_, _internal_, _conditions_).
+> _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_,
+> _conditions_).
 >1.If_resolved_isequalto**undefined**, continuetheloop.
 >1.Return_resolved_.
 >1.Return**undefined**.
 >1.Otherwise, if_target_isanArray, then
 >1.If_target.lengthiszero, return**null**.
 >1.Foreachitem_targetValue_in_target_, do
 >1.Let_resolved_betheresultof**PACKAGE_TARGET_RESOLVE**(
-> _packageURL_, _targetValue_, _subpath_, _internal_, _conditions_),
->continuingthelooponany_InvalidPackageTarget_error.
+> _packageURL_, _targetValue_, _subpath_, _pattern_, _internal_,
+> _conditions_), continuingthelooponany_InvalidPackageTarget_
+>error.
 >1.If_resolved_is**undefined**, continuetheloop.
 >1.Return_resolved_.
 >1.Returnorthrowthelastfallbackresolution**null**returnorerror.

lib/internal/modules/esm/resolve.js

@@ -307,10 +307,11 @@ function throwInvalidPackageTarget(
 }
 
 constinvalidSegmentRegEx=/(^|\\|\/)(\.\.?|node_modules)(\\|\/|$)/;
+constpatternRegEx=/\*/g;
 
 functionresolvePackageTargetString(
-target,subpath,match,packageJSONUrl,base,internal,conditions){
-if(subpath!==''&&target[target.length-1]!=='/')
+target,subpath,match,packageJSONUrl,base,pattern,internal,conditions){
+if(subpath!==''&&!pattern&&target[target.length-1]!=='/')
 throwInvalidPackageTarget(match,target,packageJSONUrl,internal,base);
 
 if(!StringPrototypeStartsWith(target,'./')){
@@ -321,8 +322,12 @@ function resolvePackageTargetString(
 newURL(target);
 isURL=true;
 }catch{}
-if(!isURL)
-returnpackageResolve(target+subpath,packageJSONUrl,conditions);
+if(!isURL){
+constexportTarget=pattern ?
+StringPrototypeReplace(target,patternRegEx,subpath) :
+target+subpath;
+returnpackageResolve(exportTarget,packageJSONUrl,conditions);
+}
 }
 throwInvalidPackageTarget(match,target,packageJSONUrl,internal,base);
 }
@@ -342,6 +347,9 @@ function resolvePackageTargetString(
 if(RegExpPrototypeTest(invalidSegmentRegEx,subpath))
 throwInvalidSubpath(match+subpath,packageJSONUrl,internal,base);
 
+if(pattern)
+returnnewURL(StringPrototypeReplace(resolved.href,patternRegEx,
+subpath));
 returnnewURL(subpath,resolved);
 }
 
@@ -356,10 +364,10 @@ function isArrayIndex(key){
 }
 
 functionresolvePackageTarget(packageJSONUrl,target,subpath,packageSubpath,
-base,internal,conditions){
+base,pattern,internal,conditions){
 if(typeoftarget==='string'){
 returnresolvePackageTargetString(
-target,subpath,packageSubpath,packageJSONUrl,base,internal,
+target,subpath,packageSubpath,packageJSONUrl,base,pattern,internal,
 conditions);
 }elseif(ArrayIsArray(target)){
 if(target.length===0)
@@ -371,8 +379,8 @@ function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
 letresolved;
 try{
 resolved=resolvePackageTarget(
-packageJSONUrl,targetItem,subpath,packageSubpath,base,internal,
-conditions);
+packageJSONUrl,targetItem,subpath,packageSubpath,base,pattern,
+internal,conditions);
 }catch(e){
 lastException=e;
 if(e.code==='ERR_INVALID_PACKAGE_TARGET')
@@ -406,7 +414,7 @@ function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
 constconditionalTarget=target[key];
 constresolved=resolvePackageTarget(
 packageJSONUrl,conditionalTarget,subpath,packageSubpath,base,
-internal,conditions);
+pattern,internal,conditions);
 if(resolved===undefined)
 continue;
 returnresolved;
@@ -460,7 +468,7 @@ function packageExportsResolve(
 if(ObjectPrototypeHasOwnProperty(exports,packageSubpath)){
 consttarget=exports[packageSubpath];
 constresolved=resolvePackageTarget(
-packageJSONUrl,target,'',packageSubpath,base,false,conditions
+packageJSONUrl,target,'',packageSubpath,base,false,false,conditions
 );
 if(resolved===null||resolved===undefined)
 throwExportsNotFound(packageSubpath,packageJSONUrl,base);
@@ -471,7 +479,13 @@ function packageExportsResolve(
 constkeys=ObjectGetOwnPropertyNames(exports);
 for(leti=0;i<keys.length;i++){
 constkey=keys[i];
-if(key[key.length-1]==='/'&&
+if(key[key.length-1]==='*'&&
+StringPrototypeStartsWith(packageSubpath,
+StringPrototypeSlice(key,0,-1))&&
+packageSubpath.length>=key.length&&
+key.length>bestMatch.length){
+bestMatch=key;
+}elseif(key[key.length-1]==='/'&&
 StringPrototypeStartsWith(packageSubpath,key)&&
 key.length>bestMatch.length){
 bestMatch=key;
@@ -480,12 +494,15 @@ function packageExportsResolve(
 
 if(bestMatch){
 consttarget=exports[bestMatch];
-constsubpath=StringPrototypeSubstr(packageSubpath,bestMatch.length);
+constpattern=bestMatch[bestMatch.length-1]==='*';
+constsubpath=StringPrototypeSubstr(packageSubpath,bestMatch.length-
+(pattern ? 1 : 0));
 constresolved=resolvePackageTarget(packageJSONUrl,target,subpath,
-bestMatch,base,false,conditions);
+bestMatch,base,pattern,false,
+conditions);
 if(resolved===null||resolved===undefined)
 throwExportsNotFound(packageSubpath,packageJSONUrl,base);
-return{ resolved,exact: false};
+return{ resolved,exact: pattern};
 }
 
 throwExportsNotFound(packageSubpath,packageJSONUrl,base);
@@ -504,7 +521,7 @@ function packageImportsResolve(name, base, conditions){
 if(imports){
 if(ObjectPrototypeHasOwnProperty(imports,name)){
 constresolved=resolvePackageTarget(
-packageJSONUrl,imports[name],'',name,base,true,conditions
+packageJSONUrl,imports[name],'',name,base,false,true,conditions
 );
 if(resolved!==null)
 return{ resolved,exact: true};
@@ -513,7 +530,13 @@ function packageImportsResolve(name, base, conditions){
 constkeys=ObjectGetOwnPropertyNames(imports);
 for(leti=0;i<keys.length;i++){
 constkey=keys[i];
-if(key[key.length-1]==='/'&&
+if(key[key.length-1]==='*'&&
+StringPrototypeStartsWith(name,
+StringPrototypeSlice(key,0,-1))&&
+name.length>=key.length&&
+key.length>bestMatch.length){
+bestMatch=key;
+}elseif(key[key.length-1]==='/'&&
 StringPrototypeStartsWith(name,key)&&
 key.length>bestMatch.length){
 bestMatch=key;
@@ -522,11 +545,14 @@ function packageImportsResolve(name, base, conditions){
 
 if(bestMatch){
 consttarget=imports[bestMatch];
-constsubpath=StringPrototypeSubstr(name,bestMatch.length);
+constpattern=bestMatch[bestMatch.length-1]==='*';
+constsubpath=StringPrototypeSubstr(name,bestMatch.length-
+(pattern ? 1 : 0));
 constresolved=resolvePackageTarget(
-packageJSONUrl,target,subpath,bestMatch,base,true,conditions);
+packageJSONUrl,target,subpath,bestMatch,base,pattern,true,
+conditions);
 if(resolved!==null)
-return{ resolved,exact: false};
+return{ resolved,exact: pattern};
 }
 }
 }

test/es-module/test-esm-exports.mjs

@@ -33,6 +33,9 @@ import fromInside from '../fixtures/node_modules/pkgexports/lib/hole.js'
 {default: 'self-cjs'} : {default: 'self-mjs'}],
 // Resolve self sugar
 ['pkgexports-sugar',{default: 'main'}],
+// Path patterns
+['pkgexports/subpath/sub-dir1',{default: 'main'}],
+['pkgexports/features/dir1',{default: 'main'}]
 ]);
 
 if(isRequire){

test/fixtures/es-modules/pkgimports/package.json

@@ -5,9 +5,9 @@
 "import": "./importbranch.js",
 "require": "./requirebranch.js"
  },
-"#subpath/": "./sub/",
+"#subpath/*": "./sub/*",
 "#external": "pkgexports/valid-cjs",
-"#external/subpath/": "pkgexports/sub/",
+"#external/subpath/*": "pkgexports/sub/*",
 "#external/invalidsubpath/": "pkgexports/sub",
 "#belowbase": "../belowbase",
 "#url": "some:url",