Add import.meta.resolve()

[domenic]

Closes #3871.

This introduces a new function, import.meta.resolve(moduleSpecifier), which returns the URL to which a given module specifier would resolve in the context of the current script. That is, it returns the URL that would be imported if you did import(moduleSpecifier).

It will throw an exception if an invalid specifier is given (including one not mapped to anywhere by an import map).

The main use case for this is to get URLs relative to the current script, or relative to a current page. For example:

// Inside https://example.com/my/deep/path/app.mjs
import.meta.resolve("./foo.txt");
// -> "https://example.com/my/deep/path/foo.txt"

or

import.meta.resolve("somepackage/resource.json")
// -> "https://example.com/node_modules/somepackage/lib/resource.json", based on
// an import map that sends "somepackage/" to "https://example.com/node_modules/somepackage/lib/".

• At least two implementers are interested (and none opposed):
  • Chromium: yes, I am implementing this
  • Gecko: yes, see discussion in this thread and in import.meta.resolve() mozilla/standards-positions#647
  • WebKit: "this looks reasonable" in import.meta.resolve() WebKit/standards-positions#2 (comment)
• Tests are written and can be reviewed and commented upon at:
  • Implement import.meta.resolve() web-platform-tests/wpt#34188
• Implementation bugs are filed:
  • Chrome: https://bugs.chromium.org/p/chromium/issues/detail?id=1296665
  • Firefox: https://bugzilla.mozilla.org/show_bug.cgi?id=1775424
  • Safari: https://bugs.webkit.org/show_bug.cgi?id=242163

(See WHATWG Working Mode: Changes for more details.)

---

/infrastructure.html ( diff )
/webappapis.html ( diff )

[guybedford]

This looks like a good start. A useful feature can be to permit a second argument to import.meta.resolve that allows providing a different baseURL for the resolution function - this lets import.meta.resolve behave both as a contextual resolver and as a more general resolver as well.

I can provide some spec along these lines if you'd be open to it?

[domenic]

I'd like to get the basic version out there first. Adding more features is a sure way to prevent this one from landing.

[annevk]

In principle this sounds reasonable to me. Would also like to hear from @jasnell, @lucacasonato, and @codehag. Do we have some kind of place where we document extensions to import.meta?

[domenic]

I guess we have https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.meta ?

[jasnell]

Yeah, I'm +1 on this. It'll be quite useful, I think.

[lucacasonato]

I have no strong opinion (maybe +0.1?). Not opposed, but I know some Node folks want this to be async. We are fine with it being sync (and would want it to be sync).

[codehag]

I don't see an issue with introducing this. I think this would be useful to test import maps, and i imagine it will be useful in such a world were import maps are the norm?

[domenic]

Awesome, thanks all for the review. I'll plan to merge this after I'm a bit more confident in the tests; I have some up initially at https://chromium-review.googlesource.com/c/chromium/src/+/3456729 but that CL is messy enough that I don't trust them yet.

[GeoffreyBooth]

Hey, can we slow this down just a bit? I’m a bit concerned with this being sync, since in Node the resolution step is async (and needs to remain so, or it would break various loaders use cases).

Taking a step back, for the non-bare case isn’t import.meta.resolve("./foo.txt") the same as new URL("./foo.txt", import.meta.url)? What’s the advantage of import.meta.resolve?

And the bare case, import.meta.resolve("somepackage/resource.json"), depends on import maps? Is there any anticipation that in the future the resolution of somepackage might be something that happens dynamically, similar to Node’s loaders? And if so, perhaps import.meta.resolve would need to be an async function so that this future dynamic resolution could take advantage of things like network calls?

[domenic]

I think a 7-month incubation period is slow enough?

It's ok for Node to use a different API than the web here.

This is different than the URL constructor because import maps, indeed. There is no plan to make that async; we never want to introduce network calls into module resolution on the web.

[GeoffreyBooth]

Put another way, is there some advantage in making this sync? If it’s async then we can maintain compatibility with Node or any platform that wants to allow customization in module resolution (and for that custom resolution to potentially be async).

[annevk]

Aside: was whatwg/js-hosts dissolved due to the creation of the Winter CG?

I was trying to make sense of the status of this in light of mozilla/standards-positions#647 and it seems like it's roughly at where we left it in February. Node.js can make this shape work, but isn't thrilled about it. Deno doesn't necessarily have a need, but if it's added it should be this shape. And browser folks being somewhat positive given that it matches how we resolve JS module specifiers. Is that accurate?

[jasnell]

Aside: was whatwg/js-hosts dissolved due to the creation of the Winter CG?

I believe that is the case, yes.

Node.js can make this shape work, but isn't thrilled about it.

That's accurate.

[GeoffreyBooth]

Node.js can make this shape work, but isn’t thrilled about it.

To add to this, please read this detailed comment about the downsides of Node making resolve sync. This is the kind of user feedback we will be dealing with if we make this change. These all strike me as very reasonable use cases, though mostly more for command-line programs than browser web apps; and I’m not sure if there will be other ways to solve these problems without an async resolve. nodejs/loaders#83 is an attempt to address this, but as a new API it would be a deviation from a cross-platform standard.

[domenic]

From my perspective, that comment displays some fundamental confusion between the resolve phases (a string operation) and the fetch phases (which includes things like checking for existence, permissions, network requests, etc.)

[GeoffreyBooth]

From my perspective, that comment displays some fundamental confusion between the resolve phases (a string operation) and the fetch phases (which includes things like checking for existence, permissions, network requests, etc.)

In Node, the resolve “phase” includes disk operations. Going back to CommonJS, require.resolve('foo') will search the hard disk for a package named foo, first in local node_modules, then globally, etc. This shipped over ten years ago. So I don’t think it’s unreasonable for users to think of these things as appropriate to occur within resolve. Deciding what to resolve to takes disk operations in Node; it’s not just a string operation. ESM resolution behaves largely the same way, though without automatic extension resolution.

[davidje13]

From my perspective, that comment displays some fundamental confusion between the resolve phases (a string operation) and the fetch phases (which includes things like checking for existence, permissions, network requests, etc.)

Hi @domenic — sorry for this being quite a delayed reply (I wasn't aware of this thread which linked to my other comment)

I'd like to clarify the use-case which led me to my other comment, which should help explain the bits which you think of as confusion on my part:

In NodeJS's current system, these imports could all resolve to the same file:

import 'bar';
import 'bar/index'; // or something else depending on bar's package.json
import './node_modules/bar/index.js';

And import 'bar'; from a sibling module might be referencing the same bar, or a different bar, depending on the file layout (specifically: which node_modules folder(s) bar lives in).

It's important to know all that before loading the module, because if they resolve to the same thing, we need to use the same instance of that module (e.g. so that any user-land global state is truly global). Once we get to the point of actually loading the module, it's too late. So we need resolve to detect that these are all the same thing and return one consistent URI for them (e.g. file:///wherever/node_modules/bar/index.js).

Now you may say that's a problem with NodeJS's import being too permissive in the specifiers it accepts, but the ability to use named imports is quite important for sharing dependencies while avoiding version conflicts. It's also pretty well established and shared with highly popular tools like WebPack and Rollup, which makes it very popular with destined-for-browser code (pre-bundling).

Import maps have of course been created to fill this need in the browser (with the intent being that all this information which was previously gathered by polling the filesystem is now available declaratively in-advance), but they are at an early stage (and only implemented in one runtime), so I for one cannot yet rely on them for this use-case (even in an experimental capacity).

I could also imagine a future need to lazy-load or even dynamically-generate import maps, especially in local environments like Node where the number of entries could be vast. Even in-browser I could imagine the need to fetch (sub) import maps on-demand once nesting / combining of maps gets more specced out, which would make the resolve call into something more interesting.

---

My preference (as a userspace developer with a vested interest in keeping parity between browsers and NodeJS) is that import.meta.resolve be defined as asynchronous. I understand that making it asynchronous has the downside that it will not be usable in synchronous contexts, but since asynchronous APIs are already quite common (and in particular used by import()), this doesn't seem likely to cause any problems. If it really truly must not be asynchronous, then it should be unavailable to userspace code until import maps are more mature and widely used, because making it synchronous now will cause problems if it turns out that module resolution is not always going to be a simple string operation (even in-browser).

[lucacasonato]

FYI, the compartments proposal at TC39 (https://github.com/tc39/proposal-compartments) also defines specifier resolving as being a synchronous operation. (grep for resolveHook).