esm: implement import.meta.main

[aduh95]

Boolean value to check if a module is run as entry point of the current
process.

ES module authors need a way to determine if their code is run as CLI or as a dependency. #49440 have some proposal, I am implementing import.meta.main because:

• it is arguably similar to the CJS pattern:

- if (module === require.main) {+ if (import.meta.main) {

• Deno has already implemented it, if we don't differ that is certainly easier for users to write code that runs everywhere.
• It was suggested originally in the import.meta proposal.

Fixes: #49440

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[jasnell]

What would the value be in a Worker thread?

[aduh95]

What would the value be in a Worker thread?

Good question! With the current implementation, it is true for the Worker entry point, and false for sub-modules. To check if the current script is run as CLI, that means you also have to check for isMainThread value... I'm not sure if that's the behaviour we want to implement, but it definitely needs documentation of this topic.

[devsnek]

I'm against this for reasons outlined in the issue

[hybrist]

I might be convinced otherwise if there's overwhelming support for this feature but I have some concerns about this pattern (see issue comments). My concerns are broadly:

1. Usually import.meta doesn't change based on how and when the module has been imported. It's already "magic ephemeral data", let's not make it more dynamic and magic.
2. This pattern encourages writing code that's inherently untestable without setting up a custom module loader from scratch.
3. (More optional preference) I would vastly prefer a solution that properly encloses optional code that is meant to run as main and doesn't also allow sprinkling that behavior into random expressions. One example I suggested was to export a main or startup function for this purpose.

[aduh95]

@jkrems regarding your first point, having a way to tell if current module is the entry point is a motivation clearly stated in the import.meta proposal. The way I understand it, it is supposed to be dynamic and magic.

I think your second point meets @devsnek's: using import.meta.main to run different code is not a good pattern. While I agree with this, I still firmly believe import.meta.main is a needed feature. My issue is currently when writing an ES module meant to be a CLI tool, there is no way to inform the user that they may have imported the wrong file:

import{isMainThread}from'worker_threads';if(!isMainThread||!import.meta.main){process.emitWarning(newError('This module should be run from CLI.'));}

Regarding your third point, while it'd fine with me, I fail to see how exporting a main function is less magical than checking a boolean value.

[devsnek]

i think package exports can disallow importing your cli entrypoint. I also believe that "you've imported the wrong file" isn't specific to cli entrypoints, there are lots of files that libraries have that shouldn't be directly imported, which is why we should seek more general solutions.

[addaleax]

I’m good with this, personally.

[aduh95]

Do we want to reconsider this? Asking because it's been recently brought up in #34882, it seems there are users looking for it.

[guybedford]

The use of import.meta.main is now highly established in the Deno ecosystem so I think it would be very benefical to move forward with this.

The other benefit of import.meta.main is it has a graceful failure when not supported, unlike most other import.meta features.

I think treating any new context as supporting import.meta.main makes sense as well so am happy with the worker support in this PR.

One pattern I also really like with import.meta.main is using it for creating in-module unit tests:

exportfunctionlib(){// ...implementation..}if(import.meta.main){assert.strictEqual(lib('unit'),'test');}

where the tests are run by just running node src/lib.js for each internal module individually.

During a build, import.meta.main can then be optimized out as it can be completely statically inferred for the build without any extra metadata.

@jkrems perhaps that counters your untestable argument in (2) :) I do like the idea of having an exports condition, but that seems complementary to this proposal. Would seeing progress on that help overcome your and @devsnek's concerns here?

[hybrist]

During a build, import.meta.main can then be optimized out as it can be completely statically inferred for the build without any extra metadata.

What I think is very unfortunate about those kinds of tests, is that they'll never run in a browser without building. So it's effectively creating a test pattern that is browser-incompatible. Not something that node has to care about but I would prefer if we wouldn't encourage the creation of node-only (or bundler-only) code.

perhaps that counters your untestable argument in (2)

It's still "untestable" with the exception of exactly this case: The code inside of the block is a test itself, will only ever run as a subprocess, and doesn't require any testing/assertion framework (block-scoped import is way less convenient than block-scoped require). It doesn't allow running multiple tests inside of the same process (or loading them through a test runner bootstrap).

The use of import.meta.main is now highly established in the Deno ecosystem so I think it would be very benefical to move forward with this.

Afaik deno is still much smaller as an ecosystem than nodejs (let alone the browser). So adding a module system feature to nodejs because deno is doing it when the feature cannot be used in browsers (likely in perpetuity), isn't really convincing to me.

All that being said: These are all ecosystem concerns, not nodejs concerns. I'd be willing to dismiss my block to this change if there's a way to import a module as main without spawning a subprocess. That would make it somewhat testable at least and enable simple wrapper binaries.

[aduh95]

The code inside of the block is a test itself, will only ever run as a subprocess[…]. It doesn't allow running multiple tests inside of the same process (or loading them through a test runner bootstrap).

Technically, it could be run on the same process using Workers.

adding a module system feature to nodejs because deno is doing it when the feature cannot be used in browsers (likely in perpetuity), isn't really convincing to me.

I suppose the web could also implement import.meta.main which would be true iif the module is run as web worker entry point. I reckon that's very speculative though, but if the feature gets traction from the community, I don't see why it couldn't happen.

If I'm being honest, the same argument applies to export function main pattern. Since there is no consensus amoung us, I was thinking maybe we could implement both behind a flag, then wait and see which gets the more popular. What do y'all think?

[hybrist]

If I'm being honest, the same argument applies to export function main pattern.

I don't think that's true. It's fairly simple to run a file using export main in the browser:

import{main}from'./entrypoint.js';main();

There's no need to parse & transform entrypoint.js, it works exactly as-is. With import.meta.main, entrypoint.jshas to be parsed and transformed. It cannot be served directly with the contents the user wrote.

[aduh95]

I don't think that's true. It's fairly simple to run a file using export main in the browser:

Yes sorry, I meant the fact that the HTML standard might implement import.meta.main is also true for export function main and is not a good argument for either at this point.

I think you're making a valid point with the browser compatibility thing, and I don't have any argument to counter that 😅

[hybrist]

Ah yes, sorry. Misread your comment about native browser support. :)

[ExE-Boss]

@jkrems
import.meta.main will simply be undefined in the browser.

The build step is about removing if (import.meta.main) { … } if statements in bundled modules that are not the entry module, because import.meta is shared in the context of the bundle:

Example:

Input:

// src/foo.jsif(import.meta.main){thrownewError(`${import.meta.url} is not an entrypoint module`);}exportfunctionfoo(){/* ... */}

// src/main.jsimport{foo}from"./foo.js";export*from"./foo.js";if(import.meta.main){console.log(foo());}

Output:

// dist/bundle.js// src/foo.jsfunctionfoo(){/* ... */}// src/main.jsif(import.meta.main){console.log(foo());}export{foo};

[hybrist]

import.meta.main will simply be undefined in the browser.

The build step is about removing if (import.meta.main) { … } if statements in bundled modules that are not the entry module, because import.meta is shared in the context of the bundle:

Yes, that's the problem. In the example above (where the thing inside of import.meta.main is a test), it's easy not to run the test but if I do want to run the test in a browser, only bundling could make the test actually run. In other words: The code in that block is 100% browser in-compatible. There's no API in the browser that could make the test usable if it's wrapped in import.meta.main.

[guybedford]

@jkrems it will likely be down to something like VM / compartments / realms to allow defining import.meta property hooks. Alternatively we could have a loader hook for this. The problem is on the one hand we are saying we can't add import.meta properties unless they can be customized, yet with the other we are stopping customization because we are saying they should be specified, but there is no way to specify anything for import.meta as the standard falls in the gap between standards bodies! So there we go.

[hybrist]

it will likely be down to something like VM / compartments / realms to allow defining import.meta property hooks.

I think that really doesn't address the usability concerns, just like loader hooks in node wouldn't. E.g. let's say somebody wrote two worker entrypoints, both using import.meta.main to guard the main logic. Now I want to run both in the same worker. Afaict with import.meta.main I just cannot. Even if there would be a loader hook, I would now have to write a custom loader hook just to compose two functions (effectively).

I get that the current UX (require.main) isn't great either - but at least it's relatively simple to load a CJS module as main (not that it's a great idea to do it repeatedly), the API is available on Module. But import.meta.main doesn't have any API to do it and the only API suggested so far (loader hook) would require starting the entire process with different flags and inspecting every single module load to match the one or two targeted modules.

Maybe there could be an API like Module.importAsMain(url)? Still doesn't work in browsers but at least allows composition in node without jumping through too many hoops.

[rektide]

please ship this. it's a huge help for a problem countless people run into regularly. allegedly it has risks and/or may not be 100% perfect for every use case (frankly i don't understand most of the concerns) but this seems straightforward & super helpful in 99.99% cases. not shipping it is really hurting us all very much. if we need a more foibled fancy alternative, let it emerge over time on some other import.meta. give us this straightforward common sense help which we very much need now.

[guybedford]

This sounds distinct from what is being discussed in #53882. It might even be a separate property like import.meta.preloading?

[avivkeller]

This sounds distinct from what is being discussed in #53882. It might even be a separate property like import.meta.preloading?

I'm not saying it's the solution do that problem, I'm just saying it was referenced, and the sources for the feature (this) are seemingly stale, so I wanted to verify they were still being worked on. (Sorry if I worded my last comment poorly)

[GeoffreyBooth]

I think since Deno supports this property we should add it if we can. I think we should go through the same process with the WinterCG registry that we went through for import.meta.filename, to ensure that our implementation is compatible with Deno's.

[avivkeller]

(AFAICT there are no specific issues/PRs blocking this issue)

[ljharb]

The block is because of the still unresolved request for changes on the PR; it should remain.

[avivkeller]

The blocked label is specific for issues/PRs blocking something, so I was trying to declutter. Feel free to re-add if needed.

[ljharb]

I dont have the ability to re-add it; it’s also blocked on WinterCG though.

[aduh95]

it’s also blocked on WinterCG though.

Is it? AFAICT import.meta.main is already defined in https://github.com/wintercg/import-meta-registry, not sure what other kind of input we should expect from WinterCG.

[ljharb]

That’s just documentation; it’s not the same as WinterCG having agreed on an interoperable implementation.

[jasnell]

Correct, the import-meta-registry is intended just to document the properties that runtimes are using. It is not intended as an endorsement.

[guybedford]

@aduh95 as authored here is it set to true when importing the main entry point from a worker?

[guybedford]

And just to be clear, my previous approval still stands. I wonder if we can get an update from @jkrems?

[hybrist]

It still feels like an awkward design choice because of things like "can't easily wrap" but those gaps could be filled with loaders or better core APIs in the future.

If nobody else has pushed a better API in X years, there's a good chance that making it easier to write more interoperable code is worth it. Would be great to have some canonical definition of the exact semantics that can be shared across runtimes. But worst case, that's what major versions are for..?

Willing to dismiss my review here to unblock progress.

It's been 5 years. It's unlikely that a better alternative materializes.

[ljharb]

Suggested change

	meta.main=Boolean(this?.isMain);
	meta.main=!!this?.isMain;

[Lordfirespeed]

Is there a performance merit to this? or is it for brevity / for consistency? (out of interest)

[ljharb]

Both, and it avoids a primordial.

[ljharb]

Suggested change

	FunctionPrototypeBind(initializeImportMeta,{ isMain }) :
	()=>initializeImportMeta({ isMain }) :

i believe an arrow is faster than binding

[Lordfirespeed]

Is it all good if I pick up from here in a new PR? It seems a bit unfair to expect @aduh95 to be keeping on top of it after 5 years 😂

[aduh95]

Superseded by #57804