Proposal: Support more import assertion types

[GeoffreyBooth]

While working on #40250, the PR that added support for the import assertions syntax in general and required it for JSON imports, @aduh95 and I discussed a follow-up PR that added support for other formats. There are two in particular that we think should be added:

• webassembly: An import of a WebAssembly module would need the assertion just like JSON modules do: import './file.wasm' assert { type: 'webassembly' }. This follows the examples in the import assertions proposal. (WebAssembly imports are currently flagged behind --experimental-wasm-modules and I think this flag should remain, at least until it becomes clear how browsers will handle WebAssembly imports.)

• javascript: Per the HTML spec, an import statement with no type assertion implies assert { type: 'javascript' }. The explicit version should also be supported, though, because there are cases like import(url, { assert: { type: dynamicType } }) where it is useful for Node to accept an explicit assertion type for modules that don’t necessarily need one.

The ES module loader has five formats defined internally (builtin, commonjs, module, json, wasm), each of which is mapped to either an assertion type (currently only 'json', for the json format) or the “implicit type,” which currently means that an import assertion type isn’t allowed for that format. I propose that we map wasm to 'webassembly'; and that we map builtin, commonjs and module to 'javascript'. The 'javascript' type could either be explicitly specified (import './file.js' assert { type: 'javascript' }) or implied (import './file.js').

These changes will align Node with the HTML spec, which is more detailed than the TC39 import assertions proposal. While Node of course doesn’t need to follow both the TC39 and HTML specs, it would be risky to not do so; any ways in which we deviate from the HTML spec could lead to cases where users can’t write code that can run without modification in both platforms. One potential example is if we disallow type: 'webassembly' and browsers require it, or vice versa. At least for the time being, until it becomes clear how import assertions shake out across the ecosystem, it seems prudent for Node’s default behavior to adhere to the most restrictive spec and for us to wait to relax our requirements until it’s clearly safe to do so. (I’m referring to the Node’s default ESM loader; user loaders can modify Node as they wish and violate the spec as they please.)

Another more-strict part of the HTML spec is that the assertion type is part of the module cache key. The TC39 spec proposal allows different ways to handle multiple imports of the same module with different assertions; the HTML spec team settled on this solution, and I think that Node should align with the HTML spec in order to have consistent behavior across platforms. What this means in practice is that assertion types cannot be optional, in the sense that an import without a declared type is treated as if it had included assert { type: 'javascript' }; no other type can be implied. I wrote more about this in a suggestion for the import assertions proposal.

This also positions Node to support new module types in the future. The only other type that I’m aware of any browsers supporting is 'css', which I haven’t read discussion around Node supporting, but currently there is no way to import native (.node) modules in ESM. This could be remedied by following the example of JSON and Wasm, by creating a new loader format and assertion type for such files. cc @MylesBorins

I’m opening this issue so that this thread can be the place for discussion of this proposal, so that we can limit the chatter on the PR that implements this to technical review of the code in that PR; “product” or “feature” debate should please happen here. cc @nodejs/modules @nodejs/loaders

[jkrems]

IIRC in the browser there's also discussions about having two different kinds of WASM imports, one for the Module and one for the Instance?

[ljharb]

Assertions are explicitly meant to be optional in the TC39 spec; it would be a mistake for node to decide to adopt constraints that it doesn't have.

[aduh95]

For folks who are not familiar with the context, the reason the HTML spec requires assertions for JSON is because file extension are meaningless for a web browser (they rely on MIME type, which may or may not be in phase with the file extension), and to let users import safely third party JSON modules (e.g. if import data from 'https://cool.api/legitData.json' was allowed, the cool.api server could sneakily serve a JS module instead, and have read/write access to the global objects, etc.).
Node.js doesn't have this limitation (because there are no MIME types for files on the file system – until we add HTTPS imports support), but imho it makes sense to align with browsers like we did when we decided that extensions will be required in the ESM specifiers, and let non-cross-platform behavior for CJS or custom loader hooks.

The reason assertionless WASM Module/Instance may still be on the table is because IIRC the debate hasn't settle whether WASM modules should be able to import JS modules. If WASM module can import JS, having an assertion is not useful because it would have the same "level of privileges" as JS modules. If not, the assertion would be mandatory for the same reasons as JSON modules. (I wasn't part of any of those discussions, if you think I'm not representing the current state of the debate accurately, please correct me).

[bmeck]

@aduh95 data imports are already supported and are affected by MIME.

[GeoffreyBooth]

data imports are already supported and are affected by MIME.

And certainly HTTPS imports will be, of course, and #36328 is in progress. I think once that lands, Node will have many of the same concerns as browsers, and will need the type assertions for the same reasons. I also think it would be very confusing if an assertion is required for some imports but not others based on whether the module is loaded from the filesystem versus over the network.

[ljharb]

I think it would be much more confusing if an application that uses no network loading was forced to pay a tax solely because of the existence of those features.

If they would be, then if anything that’s an argument against adding those features in the first place.

[bmeck]

If they would be, then if anything that’s an argument against adding those features in the first place.

Overall consumer compatibility to run in multiple environments is definitely a bigger concern for me than avoiding having an assertion in my code. If we don't support import assertions for example, we won't be able to write code that runs in both. Node should be working to make code work in a way that aids our users and I don't see explicitly trying to avoid compatibility as a useful thing. Tooling can be run ahead of time in both cases to mitigate w/e UX people want, but having the end result be the one that is maximally compatible is ideal.

[aduh95]

I think it would be much more confusing if an application that uses no network loading was forced to pay a tax solely because of the existence of those features.

If we take the use case of a JS module written as part of an npm package, the author can't know what protocol their code would run from: it could be local FS (from a node_modules folder), or it could be from unpkg.com if/when HTTPS imports will be supported.

[ljharb]

@aduh95 indeed; importers aren't supposed to have to know the format of the module they're importing - requiring an assertion imposes this burden.