lib: allow skipping source maps in node_modules

Files in `node_modules` are not authored by the user directly and the original sources are less relevant to the user. Skipping source maps in `node_modules` improves the general performance. Add `module.setSourceMapsSupport(enabled, options)` to skip source maps in `node_modules` if it is needed. This moves all source maps related API to `node:module` and this a step to promote the source maps API to stable. PR-URL: #56639 Reviewed-By: Vinícius Lourenço Claro Cardoso <[email protected]> Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

Author: legendecas

benchmark/es/error-stack.js

@@ -2,13 +2,19 @@
 
 constcommon=require('../common.js');
 constmodPath=require.resolve('../fixtures/simple-error-stack.js');
+constnodeModulePath=require.resolve('../fixtures/node_modules/error-stack/simple-error-stack.js');
+constModule=require('node:module');
 
 constbench=common.createBenchmark(main,{
-method: ['without-sourcemap','sourcemap'],
+method: [
+'without-sourcemap',
+'sourcemap',
+'node-modules-without-sourcemap',
+'node-module-sourcemap'],
 n: [1e5],
 });
 
-functionrunN(n){
+functionrunN(n,modPath){
 deleterequire.cache[modPath];
 constmod=require(modPath);
 bench.start();
@@ -22,11 +28,23 @@ function main({n, method }){
 switch(method){
 case'without-sourcemap':
 process.setSourceMapsEnabled(false);
-runN(n);
+runN(n,modPath);
 break;
 case'sourcemap':
 process.setSourceMapsEnabled(true);
-runN(n);
+runN(n,modPath);
+break;
+case'node-modules-without-sourcemap':
+Module.setSourceMapsSupport(true,{
+nodeModules: false,
+});
+runN(n,nodeModulePath);
+break;
+case'node-modules-sourcemap':
+Module.setSourceMapsSupport(true,{
+nodeModules: true,
+});
+runN(n,nodeModulePath);
 break;
 default:
 thrownewError(`Unexpected method "${method}"`);

benchmark/fixtures/node_modules/error-stack/simple-error-stack.js

@@ -1590,6 +1590,20 @@ import{findSourceMap, SourceMap } from 'node:module'
 const{findSourceMap, SourceMap } =require('node:module');
 ```
 
+### `module.getSourceMapsSupport()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns:{Object}
+ * `enabled`{boolean} If the source maps support is enabled
+ * `nodeModules`{boolean} If the support is enabled for files in `node_modules`.
+ * `generatedCode`{boolean} If the support is enabled for generated code from `eval` or `newFunction`.
+
+This method returns whether the [Source Map v3][Source Map] support for stack
+traces is enabled.
+
 <!-- Anchors to make sure old links find a target -->
 
 <a id="module_module_findsourcemap_path_error"></a>
@@ -1609,6 +1623,31 @@ added:
 `path` is the resolved path for the file for which a corresponding source map
 should be fetched.
 
+### `module.setSourceMapsSupport(enabled[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `enabled`{boolean} Enable the source map support.
+* `options`{Object} Optional
+ * `nodeModules`{boolean} If enabling the support for files in
+`node_modules`. **Default:** `false`.
+ * `generatedCode`{boolean} If enabling the support for generated code from
+`eval` or `newFunction`. **Default:** `false`.
+
+This function enables or disables the [Source Map v3][Source Map] support for
+stack traces.
+
+It provides same features as launching Node.js process with commandline options
+`--enable-source-maps`, with additional options to alter the support for files
+in `node_modules` or generated codes.
+
+Only source maps in JavaScript files that are loaded after source maps has been
+enabled will be parsed and loaded. Preferably, use the commandline options
+`--enable-source-maps` to avoid losing track of source maps of modules loaded
+before this API call.
+
 ### Class: `module.SourceMap`
 
 <!-- YAML
@@ -1709,6 +1748,7 @@ returned object contains the following keys:
 [Customization hooks]: #customization-hooks
 [ES Modules]: esm.md
 [Permission Model]: permissions.md#permission-model
+[Source Map]: https://sourcemaps.info/spec.html
 [Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
 [V8 JavaScript code coverage]: https://v8project.blogspot.com/2017/12/javascript-code-coverage.html
 [V8 code cache]: https://v8.dev/blog/code-caching-for-devs

benchmark/fixtures/node_modules/error-stack/simple-error-stack.ts

@@ -3987,7 +3987,7 @@ added:
  - v14.18.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.setSourceMapsSupport()`][] instead.
 
 * `val`{boolean}
 
@@ -4000,6 +4000,9 @@ It provides same features as launching Node.js process with commandline options
 Only source maps in JavaScript files that are loaded after source maps has been
 enabled will be parsed and loaded.
 
+This implies calling `module.setSourceMapsSupport()` with an option
+`{nodeModules:true, generatedCode:true }`.
+
 ## `process.setUncaughtExceptionCaptureCallback(fn)`
 
 <!-- YAML
@@ -4034,7 +4037,7 @@ added:
  - v18.19.0
 -->
 
-> Stability: 1 - Experimental
+> Stability: 1 - Experimental: Use [`module.getSourceMapsSupport()`][] instead.
 
 *{boolean}
 
@@ -4501,7 +4504,9 @@ cases:
 [`console.error()`]: console.md#consoleerrordata-args
 [`console.log()`]: console.md#consolelogdata-args
 [`domain`]: domain.md
+[`module.getSourceMapsSupport()`]: module.md#modulegetsourcemapssupport
 [`module.isBuiltin(id)`]: module.md#moduleisbuiltinmodulename
+[`module.setSourceMapsSupport()`]: module.md#modulesetsourcemapssupportenabled-options
 [`net.Server`]: net.md#class-netserver
 [`net.Socket`]: net.md#class-netsocket
 [`os.constants.dlopen`]: os.md#dlopen-constants

doc/api/module.md

@@ -368,8 +368,8 @@ internalBinding('process_methods').setEmitWarningSync(emitWarningSync);
 
 {
 const{
-getSourceMapsEnabled,
-setSourceMapsEnabled,
+getSourceMapsSupport,
+setSourceMapsSupport,
  maybeCacheGeneratedSourceMap,
 }=require('internal/source_map/source_map_cache');
 const{
@@ -381,10 +381,19 @@ internalBinding('process_methods').setEmitWarningSync(emitWarningSync);
 enumerable: true,
 configurable: true,
 get(){
-returngetSourceMapsEnabled();
+returngetSourceMapsSupport().enabled;
 },
 });
-process.setSourceMapsEnabled=setSourceMapsEnabled;
+process.setSourceMapsEnabled=functionsetSourceMapsEnabled(val){
+setSourceMapsSupport(val,{
+__proto__: null,
+// TODO(legendecas): In order to smoothly improve the source map support,
+// skip source maps in node_modules and generated code with
+// `process.setSourceMapsEnabled(true)` in a semver major version.
+nodeModules: val,
+generatedCode: val,
+});
+};
 // The C++ land calls back to maybeCacheGeneratedSourceMap()
 // when code is generated by user with eval() or new Function()
 // to cache the source maps from the evaluated code, if any.

doc/api/process.md

@@ -30,7 +30,7 @@ const{
 }=internalBinding('util');
 const{ decorateErrorStack, kEmptyObject }=require('internal/util');
 const{
-getSourceMapsEnabled,
+getSourceMapsSupport,
 }=require('internal/source_map/source_map_cache');
 constassert=require('internal/assert');
 constresolvedPromise=PromiseResolve();
@@ -186,7 +186,7 @@ class ModuleJob extends ModuleJobBase{
 // of missing named export. This is currently not possible because
 // stack trace originates in module_job, not the file itself. A hidden
 // symbol with filename could be set in node_errors.cc to facilitate this.
-if(!getSourceMapsEnabled()&&
+if(!getSourceMapsSupport().enabled&&
 StringPrototypeIncludes(e.message,
 ' does not provide an export named')){
 constsplitStack=StringPrototypeSplit(e.stack,'\n');

lib/internal/bootstrap/node.js

@@ -608,9 +608,17 @@ function initializeESMLoader(forceDefaultLoader){
 
 functioninitializeSourceMapsHandlers(){
 const{
-setSourceMapsEnabled,
+setSourceMapsSupport,
 }=require('internal/source_map/source_map_cache');
-setSourceMapsEnabled(getOptionValue('--enable-source-maps'));
+constenabled=getOptionValue('--enable-source-maps');
+setSourceMapsSupport(enabled,{
+__proto__: null,
+// TODO(legendecas): In order to smoothly improve the source map support,
+// skip source maps in node_modules and generated code with
+// `--enable-source-maps` in a semver major version.
+nodeModules: enabled,
+generatedCode: enabled,
+});
 }
 
 functioninitializeFrozenIntrinsics(){

lib/internal/modules/esm/module_job.js

@@ -3,6 +3,7 @@
 const{
  ArrayPrototypePush,
  JSONParse,
+ ObjectFreeze,
  RegExpPrototypeExec,
  SafeMap,
  StringPrototypeCodePointAt,
@@ -15,15 +16,15 @@ let debug = require('internal/util/debuglog').debuglog('source_map', (fn) =>{
 debug=fn;
 });
 
-const{ validateBoolean }=require('internal/validators');
+const{ validateBoolean, validateObject}=require('internal/validators');
 const{
 setSourceMapsEnabled: setSourceMapsNative,
 }=internalBinding('errors');
 const{
  defaultPrepareStackTrace,
  setInternalPrepareStackTrace,
 }=require('internal/errors');
-const{ getLazy }=require('internal/util');
+const{ getLazy, isUnderNodeModules, kEmptyObject}=require('internal/util');
 
 constgetModuleSourceMapCache=getLazy(()=>{
 const{ SourceMapCacheMap }=require('internal/source_map/source_map_cache_map');
@@ -45,30 +46,48 @@ const{fileURLToPath, pathToFileURL, URL, URLParse } = require('internal/url');
 letSourceMap;
 
 // This is configured with --enable-source-maps during pre-execution.
-letsourceMapsEnabled=false;
-functiongetSourceMapsEnabled(){
-returnsourceMapsEnabled;
+letsourceMapsSupport=ObjectFreeze({
+__proto__: null,
+enabled: false,
+nodeModules: false,
+generatedCode: false,
+});
+functiongetSourceMapsSupport(){
+// Return a read-only object.
+returnsourceMapsSupport;
 }
 
 /**
  * Enables or disables source maps programmatically.
- * @param{boolean} val
+ * @param{boolean} enabled
+ * @param{object} options
+ * @param{boolean} [options.nodeModules]
+ * @param{boolean} [options.generatedCode]
  */
-functionsetSourceMapsEnabled(val){
-validateBoolean(val,'val');
+functionsetSourceMapsSupport(enabled,options=kEmptyObject){
+validateBoolean(enabled,'enabled');
+validateObject(options,'options');
+
+const{ nodeModules =false, generatedCode =false}=options;
+validateBoolean(nodeModules,'options.nodeModules');
+validateBoolean(generatedCode,'options.generatedCode');
 
-setSourceMapsNative(val);
-if(val){
+setSourceMapsNative(enabled);
+if(enabled){
 const{
  prepareStackTraceWithSourceMaps,
 }=require('internal/source_map/prepare_stack_trace');
 setInternalPrepareStackTrace(prepareStackTraceWithSourceMaps);
-}elseif(sourceMapsEnabled!==undefined){
-// Reset prepare stack trace callback only when disabling source maps.
+}else{
 setInternalPrepareStackTrace(defaultPrepareStackTrace);
 }
 
-sourceMapsEnabled=val;
+sourceMapsSupport=ObjectFreeze({
+__proto__: null,
+ enabled,
+nodeModules: nodeModules,
+generatedCode: generatedCode,
+});
 }
 
 /**
@@ -130,14 +149,18 @@ function extractSourceMapURLMagicComment(content){
  * @param{string | undefined} sourceMapURL - the source map url
  */
 functionmaybeCacheSourceMap(filename,content,moduleInstance,isGeneratedSource,sourceURL,sourceMapURL){
-constsourceMapsEnabled=getSourceMapsEnabled();
-if(!(process.env.NODE_V8_COVERAGE||sourceMapsEnabled))return;
+constsupport=getSourceMapsSupport();
+if(!(process.env.NODE_V8_COVERAGE||support.enabled))return;
 const{ normalizeReferrerURL }=require('internal/modules/helpers');
 filename=normalizeReferrerURL(filename);
 if(filename===undefined){
 // This is most likely an invalid filename in sourceURL of [eval]-wrapper.
 return;
 }
+if(!support.nodeModules&&isUnderNodeModules(filename)){
+// Skip file under node_modules if not enabled.
+return;
+}
 
 if(sourceMapURL===undefined){
 sourceMapURL=extractSourceMapURLMagicComment(content);
@@ -185,8 +208,8 @@ function maybeCacheSourceMap(filename, content, moduleInstance, isGeneratedSourc
  * @param{string} content - the eval'd source code
  */
 functionmaybeCacheGeneratedSourceMap(content){
-constsourceMapsEnabled=getSourceMapsEnabled();
-if(!(process.env.NODE_V8_COVERAGE||sourceMapsEnabled))return;
+constsupport=getSourceMapsSupport();
+if(!(process.env.NODE_V8_COVERAGE||support.enabled||support.generated))return;
 
 constsourceURL=extractSourceURLMagicComment(content);
 if(sourceURL===null){
@@ -352,6 +375,10 @@ function findSourceMap(sourceURL){
 returnundefined;
 }
 
+if(!getSourceMapsSupport().nodeModules&&isUnderNodeModules(sourceURL)){
+returnundefined;
+}
+
 SourceMap??=require('internal/source_map/source_map').SourceMap;
 try{
 if(RegExpPrototypeExec(kLeadingProtocol,sourceURL)===null){
@@ -377,8 +404,8 @@ function findSourceMap(sourceURL){
 
 module.exports={
  findSourceMap,
-getSourceMapsEnabled,
-setSourceMapsEnabled,
+getSourceMapsSupport,
+setSourceMapsSupport,
  maybeCacheSourceMap,
  maybeCacheGeneratedSourceMap,
  sourceMapCacheToObject,