Additions to `import.meta`

[GeoffreyBooth]

Opening this issue per today’s TSC meeting. This is a spinoff from nodejs/node#49246 (review):

• Are additions to import.meta semver-major or semver-minor?
• Should additions to this shared namespace require WinterCG and/or TSC approval?

An import.meta.node namespace was floated in WinterTC55/proposal-minimum-common-api#50 (comment), but Bun objected. I think if we want to create a proprietary namespace then we need another WinterCG proposal for the namespace itself.

See also WinterTC55/proposal-minimum-common-api#54.

[richardlau]

• Should additions to this shared namespace require WinterCG and/or TSC approval?

I was under the impression that import.meta was intended to not be a shared namespace -- that implementors could add whatever made sense for their runtime. The issue then becomes if Javascript runtimes start adding useful things to it that are similar how do end users write code using them if they are not common across the runtimes? (e.g. if Bun and Node.js added different import.meta.* APIs to get the filename, how would someone write code that worked both in Bun and Node.js?)

[benjamingr]

Are additions to import.meta semver-major or semver-minor?

I think semver-minor is fine since unlike new globals I don't expect code to break when we add stuff to import.meta.

Should additions to this shared namespace require WinterCG and/or TSC approval?

I don't think we should require WinterCG approval for anything. I think we should engage with WinterCG in good faith and try to come up with standards and interoperability that work for all of us. I don't think it should block anything certainly not as a policy.

[benjamingr]

e.g. if Bun and Node.js added different import.meta.* APIs to get the filename, how would someone write code that worked both in Bun and Node.js?

In this case either Bun align (likely), Node.js would align (less but still likely) or someone would write an interop package for people who care about whether or not their code is portable across runtimes.

I do believe standardization is a good idea and asking for feedback is good.

[GeoffreyBooth]

I was under the impression that import.meta was intended to not be a shared namespace

Maybe that’s what TC39 intended, but like a few other things, that’s not what’s happened in practice. We went through years of negotiations with WHATWG to reach consensus on import.meta.resolve, and then through a yearlong PR to move loaders off-thread to match the import.meta.resolve spec defined by the HTML spec (among other reasons). I understand that there are some members of the community who feel that Node should just ignore WHATWG and other standards and do whatever we like, but I think it’s been a resolved policy for many years now that we try to adhere to standards with other runtimes whenever possible, especially whenever we implement APIs that exist in other runtimes.

The unfortunate thing is that import.meta is the only place to put APIs that want to know anything about the current module. For example, we recently added import { register } from 'node:module' and we would love to support register('./file.js') but instead users need to do register('./file.js', import.meta.url) or register(import.meta.resolve('./file.js')) because there’s no way that register can know the URL of the module that calls it; that’s just not possible, except for methods attached to import.meta. So now import.meta becomes this very prime real estate where API designers might want to attach anything that could benefit from knowing about the current or calling module; it’s not just a basket of generic static properties about the module.

In this case either Bun align (likely), Node.js would align (less but still likely) or someone would write an interop package for people who care about whether or not their code is portable across runtimes.

In general I think we want to encourage interoperability of code by default; there are plenty of authors who write packages for Node, or for browsers, that could be compatible across runtimes but because it’s not the path of least resistance, they neglect to do so. The broader user base is better served the more we can make it easy for packages to be written in a cross-compatible way by default.

What would this “interop package” look like? import.meta can only be accessed within the current module; it’s like __filename in that it’s specific to the current module and not shared with other modules. It therefore can’t be polyfilled, other than using module customization hooks to do things like rewrite the source of modules before they’re evaluated (which is a very Node-specific solution). The only reasonable way for users to write compatible code is via things like const absolutePath = import.meta.filename ?? import.meta.path (to cover Node and Bun); there’s no way to write a library to export a helper for this. These annoyances are why I think it’s especially important to adhere to standards around import.meta.

[ljharb]

fwiw, a helper would likely look something like wrap(import.meta), and then you'd access from or destructure that object the same as you would import.meta.

[GeoffreyBooth]

My takes:

• Are additions to import.meta semver-major or semver-minor?

I think semver-minor.

• Should additions to this shared namespace require WinterCG and/or TSC approval?

I think at least TSC approval, and the TSC should make an effort to get WinterCG approval too. We should also try to add whatever WHATWG adds to import.meta if we can (currently they’ve defined just import.meta.url and import.meta.resolve, both of which we support).

I also think that we should be sparing in granting approvals. There was a suggestion to add import.meta.register here, for import { register } from 'node:module', but to me that feels ridiculous: we shouldn’t be putting things here that are rarely used, just to avoid passing a second argument to a method. I think there’s probably also a performance cost in each thing that we add, as import.meta is an object created anew for every loaded module.

[ljharb]

I doubt there's actually a performance cost - {} vs { key: value } should be identically instantaneous, and adding a getter for something that needs computation should be negligible.

[mhdawson]

I think at least TSC approval, and the TSC should make an effort to get WinterCG approval too.

TSC approval aligns with my thinking at well with the expecation that the TSC should work to use the same values across runtimes when possible.

[jsumners]

I was under the impression that import.meta was intended to not be a shared namespace -- that implementors could add whatever made sense for their runtime.

Yep.

I think semver-minor

+1

I don't think we should require WinterCG approval for anything.

+1,000,000

I think we should engage with WinterCG in good faith and try to come up with standards and interoperability that work for all of us. I don't think it should block anything certainly not as a policy.

+1

I understand that there are some members of the community who feel that Node should just ignore WHATWG and other standards and do whatever we like

A couple of things from a non-maintainer perspective:

• Yes, Node should adhere to standards as much as makes sense. There are going to be standards that just plain do not make sense for Node. In particular, you mention WHATWG. That org is very explicitly designing standards for web browsers and how they should handle HTML / the DOM. It's right there in the FAQ. Node does not run in a web browser. It can be used to run tools for preparing code to run a web browser, but that is not the same thing.

• It's very frustrating to take the time to submit an improvement only to be met with "well, let's ask a bunch of other people that don't maintain the thing you are trying to improve what they think" and then block waiting on their deliberations. If something makes sense for Node then it should be considered in that light instead of "well, what if people using other things do something else?".

So now import.meta becomes this very prime real estate where API designers might want to attach anything that could benefit from knowing about the current or calling module;

That's literally the spec defined point of it, right?

In general I think we want to encourage interoperability of code by default; there are plenty of authors who write packages for Node, or for browsers, that could be compatible across runtimes but because it’s not the path of least resistance, they neglect to do so. The broader user base is better served the more we can make it easy for packages to be written in a cross-compatible way by default.

I really don't see the point. Non-browser runtimes are by definition not web browsers. It'd be an unmitigated disaster if web browsers all implemented different runtime environments because they are designed to view client agnostic web pages. That's the thing folks like WHATWG are governing. But non-browser runtimes are chosen by developers for the features (API) of those runtimes. I don't think it is unreasonable for those developers to be aware of the ramifications of their choices.

I think at least TSC approval,

Agreed.

and the TSC should make an effort to get WinterCG approval too.

Disagree.

[benjamingr]

From TSC discussion, it seems like we're gaining consensus around:

• Want feedback from @jasnell .
• Changes to import.meta should likely be semver-minor.
• Changes to import.meta should require TSC approval.
• WinterCG should be consulted with and collaborated with in good faith but is not blocking.
• Automation as a concern was raised since we currently have automation for semver-major. In order to not miss import.meta changes we should should fix our automation so these changes don't get missed.

[mcollina]

@nodejs/tsc @jasnell are there any objections with this plan?

---

Are additions to import.meta semver-major or semver-minor?

semver-minor

Should additions to this shared namespace require WinterCG and/or TSC approval?

TSC approval, plus WinterCG notified

[aduh95]

Can we clarify what TSC approval means in this context? Does that mean TSC should vote every time we want to add something to import.meta? Does that apply also to things we want to modify an existing property?