From 430e66b9b87012dd964eee3e3f91fdfad31d24bc Mon Sep 17 00:00:00 2001
From: Joe <28568841+Lordfirespeed@users.noreply.github.com>
Date: Mon, 26 May 2025 23:31:54 +0100
Subject: [PATCH 1/2] esm: implement import.meta.main

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

Implements: #57226

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/57804
Backport-PR-URL: https://github.com/nodejs/node/pull/58693
Fixes: https://github.com/nodejs/node/issues/57226
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
---
 doc/api/esm.md                                | 34 +++++++++
 lib/internal/main/worker_thread.js            | 14 ++++
 .../modules/esm/initialize_import_meta.js     |  6 +-
 lib/internal/modules/esm/loader.js            |  9 ++-
 lib/internal/modules/esm/translators.js       |  3 +-
 lib/internal/modules/esm/utils.js             | 12 ++-
 lib/internal/worker.js                        |  5 +-
 .../test-esm-import-meta-main-eval.mjs        | 74 +++++++++++++++++++
 test/es-module/test-esm-import-meta-main.mjs  | 26 +++++++
 test/es-module/test-esm-import-meta.mjs       |  2 +-
 test/fixtures/es-modules/import-meta-main.mjs |  1 +
 11 files changed, 174 insertions(+), 12 deletions(-)
 create mode 100644 test/es-module/test-esm-import-meta-main-eval.mjs
 create mode 100644 test/es-module/test-esm-import-meta-main.mjs
 create mode 100644 test/fixtures/es-modules/import-meta-main.mjs

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 14a87186aa2e9e..c7675dae16ab62 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -393,6 +393,35 @@ import { readFileSync } from 'node:fs';
 const buffer = readFileSync(new URL('./data.proto', import.meta.url));
 ```
 
+### `import.meta.main`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+* {boolean} `true` when the current module is the entry point of the current process; `false` otherwise.
+
+Equivalent to `require.main === module` in CommonJS.
+
+Analogous to Python's `__name__ == "__main__"`.
+
+```js
+export function foo() {
+  return 'Hello, world';
+}
+
+function main() {
+  const message = foo();
+  console.log(message);
+}
+
+if (import.meta.main) main();
+// `foo` can be imported from another module without possible side-effects from `main`
+```
+
 ### `import.meta.resolve(specifier)`
 
 <!-- YAML
@@ -587,6 +616,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)`.
@@ -1110,6 +1143,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
diff --git a/lib/internal/main/worker_thread.js b/lib/internal/main/worker_thread.js
index caf64728b754cc..f159022ee5bddd 100644
--- a/lib/internal/main/worker_thread.js
+++ b/lib/internal/main/worker_thread.js
@@ -203,6 +203,20 @@ port.on('message', (message) => {
         break;
       }
 
+      case 'data-url': {
+        const { runEntryPointWithESMLoader } = require('internal/modules/run_main');
+
+        RegExpPrototypeExec(/^/, ''); // Necessary to reset RegExp statics before user code runs.
+        const promise = runEntryPointWithESMLoader((cascadedLoader) => {
+          return cascadedLoader.import(filename, undefined, { __proto__: null }, true);
+        });
+
+        PromisePrototypeThen(promise, undefined, (e) => {
+          workerOnGlobalUncaughtException(e, true);
+        });
+        break;
+      }
+
       default: {
         // script filename
         // runMain here might be monkey-patched by users in --require.
diff --git a/lib/internal/modules/esm/initialize_import_meta.js b/lib/internal/modules/esm/initialize_import_meta.js
index d550656a9e6745..5c9390faa81387 100644
--- a/lib/internal/modules/esm/initialize_import_meta.js
+++ b/lib/internal/modules/esm/initialize_import_meta.js
@@ -51,12 +51,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) {
@@ -65,6 +65,8 @@ function initializeImportMeta(meta, context, loader) {
     setLazyPathHelpers(meta, url);
   }
 
+  meta.main = !!isMain;
+
   if (!loader || loader.allowImportMetaResolve) {
     meta.resolve = createImportMetaResolve(url, loader, experimentalImportMetaResolve);
   }
diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index c29cbf4914a03d..8d98d50395cf7f 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -246,10 +246,11 @@ class ModuleLoader {
    *
    * @param {string} source Source code of the module.
    * @param {string} url URL of the module.
+   * @param {{ isMain?: boolean }|undefined} context - context object containing module metadata.
    * @returns {object} The module wrap object.
    */
-  createModuleWrap(source, url) {
-    return compileSourceTextModule(url, source, this);
+  createModuleWrap(source, url, context = kEmptyObject) {
+    return compileSourceTextModule(url, source, this, context);
   }
 
   /**
@@ -288,7 +289,8 @@ class ModuleLoader {
    * @returns {Promise<object>} The module object.
    */
   eval(source, url, isEntryPoint = false) {
-    const wrap = this.createModuleWrap(source, url);
+    const context = isEntryPoint ? { isMain: true } : undefined;
+    const wrap = this.createModuleWrap(source, url, context);
     return this.executeModuleJob(url, wrap, isEntryPoint);
   }
 
@@ -636,6 +638,7 @@ class ModuleLoader {
    * @param {string} parentURL Path of the parent importing the module.
    * @param {Record<string, string>} importAttributes Validations for the
    *                                                  module import.
+   * @param {boolean} [isEntryPoint] Whether this is the realm-level entry point.
    * @returns {Promise<ModuleExports>}
    */
   async import(specifier, parentURL, importAttributes, isEntryPoint = false) {
diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
index 56d132ab7a9539..18dd32be669cd6 100644
--- a/lib/internal/modules/esm/translators.js
+++ b/lib/internal/modules/esm/translators.js
@@ -103,7 +103,8 @@ translators.set('module', function moduleStrategy(url, source, isMain) {
   source = stringify(source);
   debug(`Translating StandardModule ${url}`);
   const { compileSourceTextModule } = require('internal/modules/esm/utils');
-  const module = compileSourceTextModule(url, source, this);
+  const context = isMain ? { isMain } : undefined;
+  const module = compileSourceTextModule(url, source, this, context);
   return module;
 });
 
diff --git a/lib/internal/modules/esm/utils.js b/lib/internal/modules/esm/utils.js
index 9d6f850f667c51..9b41db8b0714b7 100644
--- a/lib/internal/modules/esm/utils.js
+++ b/lib/internal/modules/esm/utils.js
@@ -38,6 +38,7 @@ const {
 const {
   emitExperimentalWarning,
   getCWDURL,
+  kEmptyObject,
 } = require('internal/util');
 const {
   setImportModuleDynamicallyCallback,
@@ -187,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 });
 }
 
 /**
@@ -337,15 +338,22 @@ async function initializeHooks() {
  * @param {string} source Source code of the module.
  * @param {typeof import('./loader.js').ModuleLoader|undefined} cascadedLoader If provided,
  *        register the module for default handling.
+ * @param {{ isMain?: boolean }|undefined} context - context object containing module metadata.
  * @returns {ModuleWrap}
  */
-function compileSourceTextModule(url, source, cascadedLoader) {
+function compileSourceTextModule(url, source, cascadedLoader, context = kEmptyObject) {
   const hostDefinedOption = cascadedLoader ? source_text_module_default_hdo : undefined;
   const wrap = new ModuleWrap(url, undefined, source, 0, 0, hostDefinedOption);
 
   if (!cascadedLoader) {
     return wrap;
   }
+
+  const { isMain } = context;
+  if (isMain) {
+    wrap.isMain = true;
+  }
+
   // Cache the source map for the module if present.
   if (wrap.sourceMapURL) {
     maybeCacheSourceMap(url, source, wrap, false, wrap.sourceURL, wrap.sourceMapURL);
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
index 427492281647c2..22535cc9bcbf49 100644
--- a/lib/internal/worker.js
+++ b/lib/internal/worker.js
@@ -7,7 +7,6 @@ const {
   AtomicsAdd,
   Float64Array,
   FunctionPrototypeBind,
-  JSONStringify,
   MathMax,
   ObjectEntries,
   Promise,
@@ -166,8 +165,8 @@ class Worker extends EventEmitter {
       doEval = 'classic';
     } else if (isURL(filename) && filename.protocol === 'data:') {
       url = null;
-      doEval = 'module';
-      filename = `import ${JSONStringify(`${filename}`)}`;
+      doEval = 'data-url';
+      filename = `${filename}`;
     } else {
       doEval = false;
       if (isURL(filename)) {
diff --git a/test/es-module/test-esm-import-meta-main-eval.mjs b/test/es-module/test-esm-import-meta-main-eval.mjs
new file mode 100644
index 00000000000000..66171164b748bf
--- /dev/null
+++ b/test/es-module/test-esm-import-meta-main-eval.mjs
@@ -0,0 +1,74 @@
+import { spawnPromisified } from '../common/index.mjs';
+import * as fixtures from '../common/fixtures.js';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+const importMetaMainScript = `
+import assert from 'node:assert/strict';
+
+assert.strictEqual(import.meta.main, true, 'import.meta.main should evaluate true in main module');
+
+const { isMain: importedModuleIsMain } = await import(
+    ${JSON.stringify(fixtures.fileURL('es-modules/import-meta-main.mjs'))}
+);
+assert.strictEqual(importedModuleIsMain, false, 'import.meta.main should evaluate false in imported module');
+`;
+
+function wrapScriptInEvalWorker(script) {
+  return `
+  import { Worker } from 'node:worker_threads';
+  new Worker(${JSON.stringify(script)}, { eval: true });
+  `;
+}
+
+function convertScriptSourceToDataUrl(script) {
+  return new URL(`data:text/javascript,${encodeURIComponent(script)}`);
+}
+
+function wrapScriptInUrlWorker(script) {
+  return `
+  import { Worker } from 'node:worker_threads';
+  new Worker(new URL(${JSON.stringify(convertScriptSourceToDataUrl(script))}));
+  `;
+}
+
+describe('import.meta.main in evaluated scripts', () => {
+  it('should evaluate true in evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--input-type=module', '--eval', importMetaMainScript],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+
+  it('should evaluate true in worker instantiated with module source by evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--input-type=module', '--eval', wrapScriptInEvalWorker(importMetaMainScript)],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+
+  it('should evaluate true in worker instantiated with `data:` URL by evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--input-type=module', '--eval', wrapScriptInUrlWorker(importMetaMainScript)],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+});
diff --git a/test/es-module/test-esm-import-meta-main.mjs b/test/es-module/test-esm-import-meta-main.mjs
new file mode 100644
index 00000000000000..61251ceb9ed1b2
--- /dev/null
+++ b/test/es-module/test-esm-import-meta-main.mjs
@@ -0,0 +1,26 @@
+import '../common/index.mjs';
+import assert from 'node:assert/strict';
+import { Worker } from 'node:worker_threads';
+
+function get_environment() {
+  if (process.env.HAS_STARTED_WORKER) return 'in worker thread started by ES Module';
+  return 'in ES Module';
+}
+
+assert.strictEqual(
+  import.meta.main,
+  true,
+  `\`import.meta.main\` at top-level module ${get_environment()} should evaluate \`true\``
+);
+
+const { isMain: importedModuleIsMain } = await import('../fixtures/es-modules/import-meta-main.mjs');
+assert.strictEqual(
+  importedModuleIsMain,
+  false,
+  `\`import.meta.main\` at dynamically imported module ${get_environment()} should evaluate \`false\``
+);
+
+if (!process.env.HAS_STARTED_WORKER) {
+  process.env.HAS_STARTED_WORKER = 1;
+  new Worker(import.meta.filename);
+}
diff --git a/test/es-module/test-esm-import-meta.mjs b/test/es-module/test-esm-import-meta.mjs
index eace54884f7121..a2575c4d108cc1 100644
--- a/test/es-module/test-esm-import-meta.mjs
+++ b/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', 'main', 'resolve', 'url'];
 assert.deepStrictEqual(Reflect.ownKeys(import.meta), keys);
 
 const descriptors = Object.getOwnPropertyDescriptors(import.meta);
diff --git a/test/fixtures/es-modules/import-meta-main.mjs b/test/fixtures/es-modules/import-meta-main.mjs
new file mode 100644
index 00000000000000..bee2c8e2651335
--- /dev/null
+++ b/test/fixtures/es-modules/import-meta-main.mjs
@@ -0,0 +1 @@
+export const isMain = import.meta.main;

From 2fc89892abaa43f372f80009212e458e71177a92 Mon Sep 17 00:00:00 2001
From: Marco Ippolito <marcoippolito54@gmail.com>
Date: Thu, 12 Jun 2025 13:21:54 +0200
Subject: [PATCH 2/2] module: fix typescript import.meta.main

PR-URL: https://github.com/nodejs/node/pull/58661
Backport-PR-URL: https://github.com/nodejs/node/pull/58693
Fixes: https://github.com/nodejs/node/issues/58660
Reviewed-By: Xuguang Mei <meixuguang@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Jacob Smith <jacob@frende.me>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>
Reviewed-By: Pietro Marchini <pietro.marchini94@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
---
 lib/internal/modules/esm/translators.js       |  8 +-
 .../test-esm-import-meta-main-eval.mjs        | 84 ++++++++++++++++---
 test/fixtures/es-modules/import-meta-main.ts  |  1 +
 3 files changed, 78 insertions(+), 15 deletions(-)
 create mode 100644 test/fixtures/es-modules/import-meta-main.ts

diff --git a/lib/internal/modules/esm/translators.js b/lib/internal/modules/esm/translators.js
index 18dd32be669cd6..3a69558d7a3dba 100644
--- a/lib/internal/modules/esm/translators.js
+++ b/lib/internal/modules/esm/translators.js
@@ -511,17 +511,17 @@ translators.set('wasm', async function(url, source) {
 });
 
 // Strategy for loading a commonjs TypeScript module
-translators.set('commonjs-typescript', function(url, source) {
+translators.set('commonjs-typescript', function(url, source, isMain) {
   assertBufferSource(source, true, 'load');
   const code = stripTypeScriptModuleTypes(stringify(source), url);
   debug(`Translating TypeScript ${url}`);
-  return FunctionPrototypeCall(translators.get('commonjs'), this, url, code, false);
+  return FunctionPrototypeCall(translators.get('commonjs'), this, url, code, isMain);
 });
 
 // Strategy for loading an esm TypeScript module
-translators.set('module-typescript', function(url, source) {
+translators.set('module-typescript', function(url, source, isMain) {
   assertBufferSource(source, true, 'load');
   const code = stripTypeScriptModuleTypes(stringify(source), url);
   debug(`Translating TypeScript ${url}`);
-  return FunctionPrototypeCall(translators.get('module'), this, url, code, false);
+  return FunctionPrototypeCall(translators.get('module'), this, url, code, isMain);
 });
diff --git a/test/es-module/test-esm-import-meta-main-eval.mjs b/test/es-module/test-esm-import-meta-main-eval.mjs
index 66171164b748bf..9b51da45282616 100644
--- a/test/es-module/test-esm-import-meta-main-eval.mjs
+++ b/test/es-module/test-esm-import-meta-main-eval.mjs
@@ -3,17 +3,6 @@ import * as fixtures from '../common/fixtures.js';
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
-const importMetaMainScript = `
-import assert from 'node:assert/strict';
-
-assert.strictEqual(import.meta.main, true, 'import.meta.main should evaluate true in main module');
-
-const { isMain: importedModuleIsMain } = await import(
-    ${JSON.stringify(fixtures.fileURL('es-modules/import-meta-main.mjs'))}
-);
-assert.strictEqual(importedModuleIsMain, false, 'import.meta.main should evaluate false in imported module');
-`;
-
 function wrapScriptInEvalWorker(script) {
   return `
   import { Worker } from 'node:worker_threads';
@@ -33,6 +22,17 @@ function wrapScriptInUrlWorker(script) {
 }
 
 describe('import.meta.main in evaluated scripts', () => {
+  const importMetaMainScript = `
+import assert from 'node:assert/strict';
+
+assert.strictEqual(import.meta.main, true, 'import.meta.main should evaluate true in main module');
+
+const { isMain: importedModuleIsMain } = await import(
+    ${JSON.stringify(fixtures.fileURL('es-modules/import-meta-main.mjs'))}
+);
+assert.strictEqual(importedModuleIsMain, false, 'import.meta.main should evaluate false in imported module');
+`;
+
   it('should evaluate true in evaluated script', async () => {
     const result = await spawnPromisified(
       process.execPath,
@@ -72,3 +72,65 @@ describe('import.meta.main in evaluated scripts', () => {
     });
   });
 });
+
+describe('import.meta.main in typescript scripts', () => {
+  const importMetaMainTSScript = `
+import assert from 'node:assert/strict';
+
+assert.strictEqual(import.meta.main, true, 'import.meta.main should evaluate true in main module');
+
+const { isMain: importedModuleIsMain } = await import(
+    ${JSON.stringify(fixtures.fileURL('es-modules/import-meta-main.ts'))}
+);
+assert.strictEqual(importedModuleIsMain, false, 'import.meta.main should evaluate false in imported module');
+`;
+
+  it('should evaluate true in evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--experimental-strip-types',
+       '--input-type=module-typescript',
+       '--disable-warning=ExperimentalWarning',
+       '--eval', importMetaMainTSScript],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+
+  it('should evaluate true in worker instantiated with module source by evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--experimental-strip-types',
+       '--input-type=module-typescript',
+       '--disable-warning=ExperimentalWarning',
+       '--eval', wrapScriptInEvalWorker(importMetaMainTSScript)],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+
+  it('should evaluate true in worker instantiated with `data:` URL by evaluated script', async () => {
+    const result = await spawnPromisified(
+      process.execPath,
+      ['--input-type=module',
+       '--experimental-strip-types',
+       '--input-type=module-typescript',
+       '--disable-warning=ExperimentalWarning',
+       '--eval', wrapScriptInUrlWorker(importMetaMainTSScript)],
+    );
+    assert.deepStrictEqual(result, {
+      stderr: '',
+      stdout: '',
+      code: 0,
+      signal: null,
+    });
+  });
+});
diff --git a/test/fixtures/es-modules/import-meta-main.ts b/test/fixtures/es-modules/import-meta-main.ts
new file mode 100644
index 00000000000000..bee2c8e2651335
--- /dev/null
+++ b/test/fixtures/es-modules/import-meta-main.ts
@@ -0,0 +1 @@
+export const isMain = import.meta.main;