module: improve error message for top-level await in CommonJS

src/node_contextify.cc

@@ -1816,6 +1816,26 @@ bool ShouldRetryAsESM(Realm* realm,
   Utf8Value message_value(isolate, message);
   auto message_view = message_value.ToStringView();
 
+  for (const auto& error_message : throws_only_in_cjs_error_messages) {
+    if (message_view.find(error_message) != std::string_view::npos &&
+        error_message.find("await is only valid in async functions and "
+                           "the top level bodies of modules") !=
+            std::string_view::npos) {
+      const char* error_text =
+          "Top-level await is not supported in CommonJS modules. "
+          "To use top-level await, add \"type\": \"module\" to your "
+          "package.json "
+          "or rename the file to use the .mjs extension. Alternatively, wrap "
+          "the await expression in an async function. Module syntax like "
+          "import/export statements requires proper module configuration.";
+
+      isolate->ThrowException(v8::Exception::SyntaxError(
+          String::NewFromUtf8(isolate, error_text).ToLocalChecked()));
+
+      return true;
+    }
+  }
+
   // These indicates that the file contains syntaxes that are only valid in
   // ESM. So it must be true.
   for (const auto& error_message : esm_syntax_error_messages) {

test/es-module/test-esm-detect-ambiguous.mjs

@@ -246,9 +246,12 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         'await Promise.resolve(); console.log("executed");',
       ]);
 
-      strictEqual(stderr, '');
-      strictEqual(stdout, 'executed\n');
-      strictEqual(code, 0);
+      match(
+        stderr,
+        /Top-level await is not supported in CommonJS modules\. To use top-level await, add "type": "module" to your package\.json or rename the file to use the \.mjs extension/
+      );
+      strictEqual(stdout, '');
+      strictEqual(code, 1);
       strictEqual(signal, null);
     });
 
@@ -258,9 +261,12 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         fixtures.path('es-modules/tla/unresolved.js'),
       ]);
 
-      strictEqual(stderr, '');
+      match(
+        stderr,
+        /SyntaxError: Top-level await is not supported in CommonJS modules\. To use top-level await, add "type": "module" to your package\.json or rename the file to use the \.mjs extension/
+      );
       strictEqual(stdout, '');
-      strictEqual(code, 13);
+      strictEqual(code, 1);
       strictEqual(signal, null);
     });
 
@@ -270,9 +276,12 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         'await Promise.resolve(); import "node:os"; console.log("executed");',
       ]);
 
-      strictEqual(stderr, '');
-      strictEqual(stdout, 'executed\n');
-      strictEqual(code, 0);
+      match(
+        stderr,
+        /Top-level await is not supported in CommonJS modules\. To use top-level await, add "type": "module" to your package\.json or rename the file to use the \.mjs extension/
+      );
+      strictEqual(stdout, '');
+      strictEqual(code, 1);
       strictEqual(signal, null);
     });
 
@@ -282,7 +291,10 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         'function fn() { await Promise.resolve(); } fn();',
       ]);
 
-      match(stderr, /SyntaxError: await is only valid in async function/);
+      match(
+        stderr,
+        /Top-level await is not supported in CommonJS modules/
+      );
       strictEqual(stdout, '');
       strictEqual(code, 1);
       strictEqual(signal, null);
@@ -294,7 +306,11 @@ describe('Module syntax detection', { concurrency: !process.env.TEST_PARALLEL },
         'const fs = require("node:fs"); await Promise.resolve();',
       ]);
 
-      match(stderr, /ReferenceError: require is not defined in ES module scope/);
+      match(
+        stderr,
+        /SyntaxError: Top-level await is not supported in CommonJS modules\. To use top-level await, add "type": "module" to your package\.json or rename the file to use the \.mjs extension\. Alternatively, wrap the await expression in an async function\./
+      );
+
       strictEqual(stdout, '');
       strictEqual(code, 1);
       strictEqual(signal, null);