esm: implement import.meta.main

Boolean value to check if an ES Module is the entrypoint of the current process.

Implements: #57226

Author: Lordfirespeed

doc/api/esm.md

@@ -391,6 +391,29 @@ import { readFileSync } from 'node:fs';
 const buffer = readFileSync(new URL('./data.proto', import.meta.url));
 ```
 
+### `import.meta.main`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1.2 - Release candidate <!-- TODO: is this correct? -->
+
+* {boolean} `true` when the current module is the entry point of the current process; `false` otherwise.
+* Equivalent to `require.main === module` in CommonJS.  <!-- TODO: Is this still accurate? -->
+* Analogous to Python's `__name__ == "__main__"`.
+
+[`import.meta.resolve`][]
+
+```js
+function main() {
+  console.log('Hello, world!');
+}
+
+if (import.meta.main) main();
+```
+
 ### `import.meta.resolve(specifier)`
 
 <!-- YAML
@@ -607,6 +630,10 @@ These CommonJS variables are not available in ES modules.
 They can instead be loaded with [`module.createRequire()`][] or
 [`process.dlopen`][].
 
+#### No `require.main`
+
+To replace `require.main === module`, there is the [`import.meta.main`][] API.
+
 #### No `require.resolve`
 
 Relative resolution can be handled via `new URL('./local', import.meta.url)`.
@@ -1167,6 +1194,7 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
 [`import()`]: #import-expressions
 [`import.meta.dirname`]: #importmetadirname
 [`import.meta.filename`]: #importmetafilename
+[`import.meta.main`]: #importmetamain
 [`import.meta.resolve`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve
 [`import.meta.url`]: #importmetaurl
 [`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import

lib/internal/modules/esm/initialize_import_meta.js

@@ -49,12 +49,12 @@ function createImportMetaResolve(defaultParentURL, loader, allowParentURL) {
 /**
  * Create the `import.meta` object for a module.
  * @param {object} meta
- * @param {{url: string}} context
+ * @param {{url: string, isMain?: boolean}} context
  * @param {typeof import('./loader.js').ModuleLoader} loader Reference to the current module loader
  * @returns {{dirname?: string, filename?: string, url: string, resolve?: Function}}
  */
 function initializeImportMeta(meta, context, loader) {
-  const { url } = context;
+  const { url, isMain } = context;
 
   // Alphabetical
   if (StringPrototypeStartsWith(url, 'file:') === true) {
@@ -70,6 +70,7 @@ function initializeImportMeta(meta, context, loader) {
   }
 
   meta.url = url;
+  meta.main = !!isMain;
 
   return meta;
 }

lib/internal/modules/esm/translators.js

@@ -104,6 +104,7 @@ translators.set('module', function moduleStrategy(url, source, isMain) {
   debug(`Translating StandardModule ${url}`);
   const { compileSourceTextModule } = require('internal/modules/esm/utils');
   const module = compileSourceTextModule(url, source, this);
+  if (isMain) module.isMain = true;  // todo: is this fine?
   return module;
 });
 

lib/internal/modules/esm/utils.js

@@ -188,7 +188,7 @@ function registerModule(referrer, registry) {
  */
 function defaultInitializeImportMetaForModule(meta, wrap) {
   const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
-  return cascadedLoader.importMetaInitialize(meta, { url: wrap.url });
+  return cascadedLoader.importMetaInitialize(meta, { url: wrap.url, isMain: wrap.isMain });
 }
 
 /**

test/es-module/test-esm-import-meta-main.mjs

@@ -0,0 +1,11 @@
+import { mustCall } from '../common/index.mjs';
+import fixtures from '../common/fixtures.js';
+import assert from 'assert';
+
+assert.strictEqual(import.meta.main, true);
+
+import(fixtures.path('/es-modules/import-meta-main.mjs')).then(
+  mustCall(({ isMain }) => {
+    assert.strictEqual(isMain, false);
+  })
+);

test/es-module/test-esm-import-meta.mjs

@@ -3,7 +3,7 @@ import assert from 'assert';
 
 assert.strictEqual(Object.getPrototypeOf(import.meta), null);
 
-const keys = ['dirname', 'filename', 'resolve', 'url'];
+const keys = ['dirname', 'filename', 'resolve', 'url', 'main'];
 assert.deepStrictEqual(Reflect.ownKeys(import.meta), keys);
 
 const descriptors = Object.getOwnPropertyDescriptors(import.meta);

test/fixtures/es-modules/import-meta-main.mjs

@@ -0,0 +1 @@
+export const isMain = import.meta.main;