module: eliminate performance cost of detection for cjs entry

GeoffreyBooth · marco-ippolito · commit 132a5c190f46 · 2025-02-11T11:55:34.000+01:00
PR-URL: #52093 Backport-PR-URL: #56927 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Yagiz Nizipli <yagiz.nizipli@sentry.io> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Richard Lau <rlau@redhat.com> Refs: #52697
diff --git a/benchmark/misc/startup-core.js b/benchmark/misc/startup-core.js
@@ -9,6 +9,7 @@ const bench = common.createBenchmark(main, {
   script: [
     'benchmark/fixtures/require-builtins',
     'test/fixtures/semicolon',
+    'test/fixtures/snapshot/typescript',
   ],
   mode: ['process', 'worker'],
   n: [30],
diff --git a/lib/internal/modules/cjs/loader.js b/lib/internal/modules/cjs/loader.js
@@ -106,6 +106,7 @@ module.exports = {
   kModuleExportNames,
   kModuleCircularVisited,
   initializeCJS,
+  entryPointSource: undefined, // Set below.
   Module,
   wrapSafe,
   kIsMainSymbol,
@@ -1392,8 +1393,15 @@ function wrapSafe(filename, content, cjsModuleInstance, codeCache) {
     return result;
   } catch (err) {
     if (process.mainModule === cjsModuleInstance) {
-      const { enrichCJSError } = require('internal/modules/esm/translators');
-      enrichCJSError(err, content, filename);
+      if (getOptionValue('--experimental-detect-module')) {
+        // For the main entry point, cache the source to potentially retry as ESM.
+        module.exports.entryPointSource = content;
+      } else {
+        // We only enrich the error (print a warning) if we're sure we're going to for-sure throw it; so if we're
+        // retrying as ESM, wait until we know whether we're going to retry before calling `enrichCJSError`.
+        const { enrichCJSError } = require('internal/modules/esm/translators');
+        enrichCJSError(err, content, filename);
+      }
     }
     throw err;
   }
diff --git a/lib/internal/modules/helpers.js b/lib/internal/modules/helpers.js
@@ -19,6 +19,15 @@ const {
 } = require('internal/errors').codes;
 const { BuiltinModule } = require('internal/bootstrap/realm');
 
+const {
+  shouldRetryAsESM: contextifyShouldRetryAsESM,
+  constants: {
+    syntaxDetectionErrors: {
+      esmSyntaxErrorMessages,
+      throwsOnlyInCommonJSErrorMessages,
+    },
+  },
+} = internalBinding('contextify');
 const { validateString } = require('internal/validators');
 const fs = require('fs'); // Import all of `fs` so that it can be monkey-patched.
 const internalFS = require('internal/fs/utils');
@@ -329,6 +338,31 @@ function urlToFilename(url) {
   return url;
 }
 
+let esmSyntaxErrorMessagesSet; // Declared lazily in shouldRetryAsESM
+let throwsOnlyInCommonJSErrorMessagesSet; // Declared lazily in shouldRetryAsESM
+/**
+ * After an attempt to parse a module as CommonJS throws an error, should we try again as ESM?
+ * We only want to try again as ESM if the error is due to syntax that is only valid in ESM; and if the CommonJS parse
+ * throws on an error that would not have been a syntax error in ESM (like via top-level `await` or a lexical
+ * redeclaration of one of the CommonJS variables) then we need to parse again to see if it would have thrown in ESM.
+ * @param {string} errorMessage The string message thrown by V8 when attempting to parse as CommonJS
+ * @param {string} source Module contents
+ */
+function shouldRetryAsESM(errorMessage, source) {
+  esmSyntaxErrorMessagesSet ??= new SafeSet(esmSyntaxErrorMessages);
+  if (esmSyntaxErrorMessagesSet.has(errorMessage)) {
+    return true;
+  }
+
+  throwsOnlyInCommonJSErrorMessagesSet ??= new SafeSet(throwsOnlyInCommonJSErrorMessages);
+  if (throwsOnlyInCommonJSErrorMessagesSet.has(errorMessage)) {
+    return /** @type {boolean} */(contextifyShouldRetryAsESM(source));
+  }
+
+  return false;
+}
+
+
 // Whether we have started executing any user-provided CJS code.
 // This is set right before we call the wrapped CJS code (not after,
 // in case we are half-way in the execution when internals check this).
@@ -362,6 +396,7 @@ module.exports = {
   loadBuiltinModule,
   makeRequireFunction,
   normalizeReferrerURL,
+  shouldRetryAsESM,
   stripBOM,
   toRealPath,
   hasStartedUserCJSExecution() {
diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
@@ -4,7 +4,6 @@ const {
   StringPrototypeEndsWith,
 } = primordials;
 
-const { containsModuleSyntax } = internalBinding('contextify');
 const { getOptionValue } = require('internal/options');
 const path = require('path');
 const { pathToFileURL } = require('internal/url');
@@ -85,10 +84,6 @@ function shouldUseESMLoader(mainPath) {
     case 'commonjs':
       return false;
     default: { // No package.json or no `type` field.
-      if (getOptionValue('--experimental-detect-module')) {
-        // If the first argument of `containsModuleSyntax` is undefined, it will read `mainPath` from the file system.
-        return containsModuleSyntax(undefined, mainPath);
-      }
       return false;
     }
   }
@@ -153,12 +148,43 @@ function runEntryPointWithESMLoader(callback) {
  * by `require('module')`) even when the entry point is ESM.
  * This monkey-patchable code is bypassed under `--experimental-default-type=module`.
  * Because of backwards compatibility, this function is exposed publicly via `import { runMain } from 'node:module'`.
+ * When `--experimental-detect-module` is passed, this function will attempt to run ambiguous (no explicit extension, no
+ * `package.json` type field) entry points as CommonJS first; under certain conditions, it will retry running as ESM.
  * @param {string} main - First positional CLI argument, such as `'entry.js'` from `node entry.js`
  */
 function executeUserEntryPoint(main = process.argv[1]) {
   const resolvedMain = resolveMainPath(main);
   const useESMLoader = shouldUseESMLoader(resolvedMain);
-  if (useESMLoader) {
+
+  // Unless we know we should use the ESM loader to handle the entry point per the checks in `shouldUseESMLoader`, first
+  // try to run the entry point via the CommonJS loader; and if that fails under certain conditions, retry as ESM.
+  let retryAsESM = false;
+  if (!useESMLoader) {
+    const cjsLoader = require('internal/modules/cjs/loader');
+    const { Module } = cjsLoader;
+    if (getOptionValue('--experimental-detect-module')) {
+      try {
+        // Module._load is the monkey-patchable CJS module loader.
+        Module._load(main, null, true);
+      } catch (error) {
+        const source = cjsLoader.entryPointSource;
+        const { shouldRetryAsESM } = require('internal/modules/helpers');
+        retryAsESM = shouldRetryAsESM(error.message, source);
+        // In case the entry point is a large file, such as a bundle,
+        // ensure no further references can prevent it being garbage-collected.
+        cjsLoader.entryPointSource = undefined;
+        if (!retryAsESM) {
+          const { enrichCJSError } = require('internal/modules/esm/translators');
+          enrichCJSError(error, source, resolvedMain);
+          throw error;
+        }
+      }
+    } else { // `--experimental-detect-module` is not passed
+      Module._load(main, null, true);
+    }
+  }
+
+  if (useESMLoader || retryAsESM) {
     const mainPath = resolvedMain || main;
     const mainURL = pathToFileURL(mainPath).href;
 
@@ -167,10 +193,6 @@ function executeUserEntryPoint(main = process.argv[1]) {
       // even after the event loop stops running.
       return cascadedLoader.import(mainURL, undefined, { __proto__: null }, true);
     });
-  } else {
-    // Module._load is the monkey-patchable CJS module loader.
-    const { Module } = require('internal/modules/cjs/loader');
-    Module._load(main, null, true);
   }
 }
 
diff --git a/src/node_contextify.cc b/src/node_contextify.cc
diff --git a/src/node_contextify.h b/src/node_contextify.h
