doc: clarify require/import complement exclusivity

[guybedford]

This PR adds a small doc change to clearly define that "import" and "require" are always mutually exclusive in exports (if something was not required then it definitely was imported) when loading an ES module.

Currently there isn't clear guidance that when defining in "exports":

{
  "exports": {
    "import": "./main.mjs",
    "require": "./main.cjs",
    "default": "./main.js"
  }
}

that it should never be possible to resolve to ./main.js.

For example, other tools and bundlers could interpret new Worker('pkg') to not be an import or require path at all. Or similarly for other mechanisms of loading in future. When we should always define that loading an ES module goes through the import path.

Otherwise, this leaves a semantic gap where users might find default matched by some tools in the above example. By narrowing this gap we ensure we can continue to provide predictability between tools.

//cc @nodejs/modules-active-members

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[guybedford]

//cc @sokra

[jkrems]

Technically there may be "classic-script" as a 3rd option but I'm fine with pretending that it doesn't exists, as far as exports is concerned. Classic scripts don't have a notion of "import specifiers", really.

[bmeck]

I'd just note that "mutual exclusivity" doesn't mean one or the other must be true, just that they both cannot be true, so it seems the example in the original comment about not being able to hit default still isn't clear from the doc change.

[guybedford]

Thanks @bmeck for the logical assistance here... ok I've changed the wording to be explicit they that are fully complementary in matching. Let me know if that sounds better.

[bmeck]

sounds good

[sokra]

I don't agree with that. That might be true for node in the current state, but I don't think that should be a general precondition.

Other conditions should be allowed for future extensions or alternative module formats.

Esm might be superseded by a new module format in a long distant future. For this you might want to use a new condition zap to point to the zap modules.

Non JavaScript module systems also want to use a different condition. For a css module using @import "package" you may want to use the @import condition name.

[sokra]

Mutually exclusive seems fine to me. Meaning when import is defined, require is never defined, and vise versa.

[jkrems]

To clarify here: the condition is called “import” because it refers to a module graph, not to a module file format. So it may point to a web assembly module or a JSON module, assuming those can be linked into an import-style graph of modules. Just like “require” doesn’t mean CommonJS file format. It could also point to .node or .json files which are also supported in require-style module graphs (potentially).

[guybedford]

@sokra would it help if we specifically adjust the wording to distinguish between module and asset where asset can imply things like CSS references that are not represented by modules in the module graph? As @jkrems mentions, WebAssembly et al should still be considered as modules under this interpretation so they would be loadable under import.

[guybedford]

Landed in f89530f.