Docs/review of various affects of type field

[bmeck]

"type" in package.json has a few affects:

• when loading the main entrypoint of the process or a worker thread it can determine which loader to use: ESM loader (if package.type is "module") vs CJS loader (if type is anything else? [this seems a forwards compat bug?] )
• manipulates format resolution within its package boundary
  • .js and extension-less files in particular
  • also .node
• causes the CJS loader to error for CJS format files that end in .js within that package boundary (not extension-less files?)

We should probably document and/or bugfix these if they are not the expected behavior.

[jkrems]

Thanks for collecting that list!

when loading the main entrypoint of the process or a worker thread it can determine which loader to use: ESM loader (if package.type is "module") vs CJS loader (if type is anything else?

That sounds like a bug or at least unexpected behavior. The loader for the entry point should be determined by the file format of the entry point, not by the closest package.json#type. E.g. if I'm in type:module and run node foo.cjs, I wouldn't expect the import loader to be involved.

causes the CJS loader to error for CJS format files that end in .js within that package boundary (not extension-less files?)

Yep, sounds inconsistent to me. It should complain on all "explicitly ESM or otherwise incompatible files", regardless of the type field and which of the well-known ESM types are present. There are some challenges with how loader hooks could influence format determination though.

[bmeck]

That sounds like a bug or at least unexpected behavior. The loader for the entry point should be determined by the file format of the entry point, not by the closest package.json#type. E.g. if I'm in type:module and run node foo.cjs, I wouldn't expect the import loader to be involved.

It is if a .cjs or .mjs is seen, but the algorithm is actually a bit more complex to reason about than just that, see shouldUseESMLoader's impl

[GeoffreyBooth]

• manipulates format resolution within its package boundary

  • .js and extension-less files in particular
  • also .node

For .js and extensionless this was the intended behavior, though I think we should talk about whether extensionless files should be supported. I think that kind of slipped in without much consideration.

.node should be unaffected by "type". Whether import works or doesn’t work for .node files is not something I think we’ve decided; the docs say “An import statement can reference an ES module or a CommonJS module. Other file types such as JSON or Native modules are not supported. For those, use module.createRequire().” So either the docs are wrong or the implementation is wrong, but for sure the "type" field should have no effect on whether import of .node succeeds.

• causes the CJS loader to error for CJS format files that end in .js within that package boundary (not extension-less files?)

Just as require('./file.mjs') throws, so should require('./file.js') under type: module since those .js files are defined as being ESM/equivalent to .mjs files. Also require('extensionless') should also throw under type: module.

[MylesBorins]

removing the modules-agenda label for now. Please feel free to re-add