Does this PR need anything else? @Trott?

I’d like to get this merged in sooner than later because #29494 will make further changes to the ESM docs, and it would be good to get this in before that.

@nodejs/documentation @nodejs/modules @nodejs/collaborators This could use some reviews.

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3904/

Anyone care to review? 🙋

Lite CI: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/3911/

not sure if late for this party, but as soon as you decide to reserve an entry in package.json, maybe it makes more sense to make it flexible, able to scale.

"type": "commonjs" limits the scope of the type property to a single type, which might be fine, but how about using type as an object instead, where multiple types are meant?

{
  // backward compatible
  "main": "cjs/index.js",
  "type": {
    "commonjs": "cjs/index.js",
    "esm": "esm/index.mjs",
    "json": "json/index.json",
    "wasm": "wasm/index.wasm"
  }
}

Something like that would help dual, triple, quadruple package modules that could include present and future of any format we could come up with.

TL;DR why would type be limited to a single use case, where in a transition phase, and in a multi-module publishing, we could have all pointers in that very same place?

@WebReflection sounds like you're asking for nodejs/modules#283 :-)

not sure if late for this party, but as soon as you decide to reserve an entry in package.json, maybe it makes more sense to make it flexible, able to scale.

This is outside the scope of this PR, but it’s under development in nodejs/modules#368.

I don't think type is a meaningful differentiator there. I don't think "let people load .wasm as image/png!" is a use case node needs to support. .js is - afaik - the only truly ambiguous file extension that has different interpretations inside of node.

@ljharb @GeoffreyBooth thanks, not sure it's the same, but I'll have a look

@jkrems

.js is - afaik - the only truly ambiguous file

what I've said has nothing to do with .js, it's about the module.

A dual module would like to point at both CJS and ESM, but if loaded via WASM (in the future) it could point at WASM too, whenever it'll get some module namespace.

Having a type field that describes a single module type is limiting already for dual packages modules, so that having an entry that would scale any scenario would be, IMHO, wiser at this point, as every trouble we had so far was because we never thought .js or, in general, an npm module, could be anything different than CJS, so that avoiding the same mistake now, for any future iteration of NodeJS modules, would be ideal.

I'm not sure what you mean by "loaded as WASM" - wouldn't you expect that if the same package is reachable from JS and WASM, it would do the same thing / point to the same thing? In my head those boundaries between modules shouldn't care that either side is WASM or JS..? I would expect that if I have gone through the pains of shipping a binary AST format in the future, it would always be used even if the importing module happens to be written in plain JS.

@WebReflection please open an issue in https://github.com/nodejs/modules if you don’t mind, this PR is just a documentation update 😄

I would expect that if I have gone through the pains of shipping a binary AST format in the future, it would always be used even if the importing module happens to be written in plain JS.

if the bundler doesn't understand that, it can fallback.
if the WASM module loader wouldn't find the WASM, it can fallback.

and so on and so forth, there are not just two kind of modules, as there was never just one kind, hence my comment.

@GeoffreyBooth if you think it's needed, I will.

Regaards

As ES Modules are Experimental and therefore subject to any and all changes in any version for the time being, I'm going to go ahead and land this documentation update. Changes to type (and anything else in ES Modules in Node.js) are totally fair game and we'll just update the docs again if/when those changes happen.

Landed in 80cc6f5