esm: implement import.meta.main

[Lordfirespeed]

Implements #57226

This PR supersedes #32223

Fixes: #57226

[nodejs-github-bot]

Review requested:

• @nodejs/loaders

[Lordfirespeed]

@ljharb I would appreciate your review on this r.e. performance - I am particularly concerned about my changes in lib/internal/modules/esm/translators.js, since I'm not familiar with implications of assignment to a JS object associated with a native object.

[codecov]

Codecov Report

Attention: Patch coverage is 94.59459% with 2 lines in your changes missing coverage. Please review.

Project coverage is 90.22%. Comparing base (b197355) to head (41d80f0).
Report is 222 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/main/worker_thread.js	92.85%	1 Missing ⚠️
lib/internal/modules/esm/loader.js	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #57804      +/-   ##
==========================================
- Coverage   90.23%   90.22%   -0.02%     
==========================================
  Files         633      633              
  Lines      186818   186844      +26     
  Branches    36668    36682      +14     
==========================================
- Hits       168578   168575       -3     
- Misses      11036    11045       +9     
- Partials     7204     7224      +20     

Files with missing lines	Coverage Δ
lib/internal/modules/esm/initialize_import_meta.js	100.00% <100.00%> (ø)
lib/internal/modules/esm/translators.js	91.59% <100.00%> (+0.01%)	⬆️
lib/internal/modules/esm/utils.js	98.94% <100.00%> (+0.02%)	⬆️
lib/internal/worker.js	99.82% <100.00%> (-0.01%)	⬇️
lib/internal/main/worker_thread.js	94.40% <92.85%> (-0.08%)	⬇️
lib/internal/modules/esm/loader.js	95.98% <80.00%> (-0.09%)	⬇️

... and 36 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Lordfirespeed]

@ljharb I've moved the assignment into compileSourceTextModule, but I'm a bit confused

I think I can see where the cache is populated, but not where it is hit in compileSourceTextModule (unless it's in CPP?)
That leads me to think the cache gets hit at some point before the standard moduleStrategy function is used, which would mean moving the assignment either has no effect or is detrimental.

What am I missing?

[Lordfirespeed]

I think CI should pass now. make -j$(nproc) test is passing locally.

[Lordfirespeed]

I checked locally, it seems the test no longer fails with unusual character names using a relative import path.

[mcollina]

lgtm

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @mcollina.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/66343/

[targos]

There's a test for import.meta.main === false, but not for true, I think?

[LiviaMedeiros]

There's a test for import.meta.main === false, but not for true, I think?

There is:

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

Line 4 in 37091e6

assert.strictEqual(import.meta.main, true);

But it would still be nice to cover more cases, e.g.:

• worker threads
• child process (exec, fork)
• --eval

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/66367/

[nodejs-github-bot]

Landed in bbc0593

[rauschma]

Question: Given that this is a boolean and not a string like require.main – should the name be import.meta.isMain?

[Lordfirespeed]

@rauschma please read #49440 and #57226.

In particular, see WinterCG's import.meta registry.

WinterCG compliant runtimes should never use an import.meta property that conflicts in definition with any of the properties included in this registry.

Likewise, implementations should try their best to avoid adding new import.meta properties in their implementations, or to this registry, that conflict or overlap with other properties in this registry. Given that such conflict/overlap may not be always avoidable, registrations here should take care to describe when/where/how such properties differ from others they conflict/overlap with.

[js-choi]

@rauschma: The conversation most relevant to main vs. isMain starts at #57226 (comment).

Basically, yes, it probably should have been named import.meta.isMain, but the one who implemented it first got to name it, and others need to follow suit to avoid excessive proliferation of import.meta properties. It’s an issue of compatibility with the first mover.

This naming mistake happened before WinterTC was established. Hopefully WinterTC’s import.meta registry coordination will make it more likely that such mistakes will be caught before shipping.

[rauschma]

Right, prior art trumps all other considerations in this case. Thanks for the information @Lordfirespeed and @js-choi!

[ljharb]

"main" isn't a good name for the concept either :-) but we're stuck with it.

[aduh95]

test/parallel/test-worker-data-url.js is failing on v22.x with this change. Manual backport PR would be required if we want it on v22.x release line.

[Lordfirespeed]

@aduh95 I'm happy to do the work for the v22 backport. Is there a section of the contributing docs I should look at for guidance?

[aduh95]

There's

node/doc/contributing/backporting-to-release-lines.md

Line 35 in 5e87577

## Submitting a backport pull request