Proposal: import.meta.resolve (was: import.meta.resolveURL)

[guybedford]

Motivation

With import.meta.url support in Module Scripts, common asset loading workflows look something like the following:

const response = await fetch(new URL('../hamsters.jpg', import.meta.url).href);
const worker = new Worker(new URL('./worker.js', import.meta.url).href, { type: 'module' });

With an import.meta.resolveURL function, these workflows can be simplified to:

const response = await fetch(import.meta.resolveURL('../hamsters.jpg'));
const worker = new Worker(import.meta.resolveURL('./worker.js'), { type: 'module' });

much more clearly indicating the intent of these common loading scenarios.

The added benefit of the above is that we bring static analyzability back to these workflows, in that build tools can now statically determine where assets and workers are being resolved and handle rewriting of these kinds of expressions. In this way assets and workers can much more easily be updated to point to optimized resources during builds than requiring build tools to try and analyze custom URL manipulations, which may vary more than the initial examples above and lead to more unreliable results. This would, for example, be useful for us in Rollup to be able to provide these optimizations more easily to users.

Proposal

The proposal is a function of the following form:

resolveURL (url: string): string

Which returns the WhatWG URL normalization applied for url relative to import.meta.url, and returning the fully normalized URL string.

I'd be happy to assist with any spec work here as well.

Feedback welcome!

[annevk]

Bikeshed: I'm not sure if we want to continue to use "resolve" for this, since the URL Standard doesn't really have that concept. The alternative would be "parseURL".

[domenic]

I'm strongly in favor of this, although I realize there is indeed a bikeshedding question here. /cc @whatwg/modules for thoughts, especially implementer interest.

Spec-wise, it seems like you'd create one function object per module script... no other real choices I can see. Seems fine. Might be a bit fun figuring out whether to use any IDL formalisms or just JS style spec.

The bikeshedding is indeed probably the biggest issue here. I think "resolve" is the typical user-exposed name for this operation in a module context; see e.g. Node.js or Webpack. (I thought this went back to the CommonJS standard or AMD as well, but I can't find any evidence.) I guess that's more about module identifiers though.

I think we should just run with that, in fact: we should just use the name "resolve", and let this it work on all module resolution. This doesn't matter now, but with package name maps it would then allow nice things like import.meta.resolve("lodash/fp.js").

[dcleao]

@domenic Will there be a way to know the package name of the current module/package, something like import.meta.packageName?

[hiroshige-g]

import.meta.resolve("lodash/fp.js")

This looks nice, but conflicts with relative path URLs without leading .. For example,

new URL('hamsters.jpg', import.meta.url).href

returns something like https://example.com/baseurl/hamsters.jpg while

import.meta.resolve('hamsters.jpg')

might tries to resolve hamsters.jpg as a package name.

Two functions might be needed (one for parseURL and one for #resolve-a-module-specifier).

[hiroshige-g]

@dcleao I expect No.
A module script can be imported using multiple names or a URL from multiple module scripts, and thus we can't reliably/deterministically determine which name is to be used.
There are similar concerns related to import.meta.scriptElement https://github.com/tc39/proposal-import-meta/blob/master/HTML%20Integration.md.

For example,

• Both packageName1 and packageName2 are resolved to https://example.com/foo.js by a package name map.
• a.js, b.js and c.js imports packageName1, packageName2, and https://example.com/foo.js, respectively, and all of them result in a single foo.js to be loaded.

In this case, it's not clear what import.meta.packageName should return in foo.js (packageName1, packageName2, or null?).

[benjamingr]

I've also been following this discussion on the nodejs modules side and am strongly in favour of this. This would simplify a lot of workflows for people using our new APIs (like Worker, mentioned above). I think it could also bring similar benefits to people writing code on the client.

[domenic]

@hiroshige-g you're right about the potential "conflict". However, I am not sure there are any consumers who really insist on typing import.meta.resolve('hamsters.jpg') instead of import.meta.resolve('./hamsters.jpg'). In contrast, giving web authors two methods which behave very similarly, with slight differences around how they treat unprefixed strings, seems like a high burden.

[bmeck]

I have concerns with this being Synchronous if there is intent for this to be shared with Node in any way. The current design of ESM loaders in Node is with asynchronous resolution. If this API was asynchronous it seems like it wouldn't introduce a bottleneck if a microtask was added to resolve when compared to the cost of fetching/loading a Module. That said, I think this API should return a Promise and be asynchronous.

Per import.meta.resolve('hamsters.jpg'), I would be surprised if this worked currently because hanging the API off of import. I would expect it to work like import resolution does; just as @domenic says I think there is a burden we can avoid by making these things match.

In addition, without it being more than just sugar for new URL(..., import.meta.url) it seems like this convenience API isn't really worth it. Whenever/however bare specifiers are supported and this API no longer is such a simple sugar it seems more valuable.

[domenic]

Yeah, we wouldn't make this async on the web, so Node may not be able to match, it's true. Node may want a different name for its async resolution algorithm.

[bmeck]

@domenic I'd prefer to use resolve() our caching and import.meta.url already don't 100% match so I think divergence already occurred. I'm not sure why it wouldn't be ok as async on the web, if you could explain that.

[domenic]

On the web URL and module specifier resolution is synchronous.