Rename configuration options to avoid "type" term

[bmeck]

We have seen this in a few places, but it seems we should discuss why to use the term "type" if it is used for determining how to interpret contents. We have seen arguments about familiarity in this area regarding the browser attribute, but also how familiarity caused --entry-type to be confused in the same browser familiarity. We have seen concern about collision with the term for JS API types which are types when talking about file types, input types, or package types. We have also seen a minor concern about existing fields with similar named in the ecosystem, which could have affects due to typos or people thinking they are related (some systems in the past I have used allowed both singular and plural term when configuring things). We have also seen a concern about scalability of any field we ship not just in number of values it accepts, but also in file extensions it can cover.

Perhaps we could use a more specific term such as how we used to use "formats" to at least cut off some of the collision or confusion. Or perhaps a more specific term for the same effect. Writing dialogue about how humans can talk to each other through readmes, messages, or verbal communication while talking about other things that also use the term "type" might help explain this a bit better.

Overall it seems like there are downsides to the term "type" and I am hopeful we can find an alternative that allows fewer concerns while adding clarity to how we communicate around the configuration.

[ljharb]

I totally agree; “format” makes much more sense to me, for example.

[guybedford]

Perhaps we should consider changing --input-type in nodejs/node#27184 to --input-format then?

[GeoffreyBooth]

I think “type” and “format” are just synonyms. I don’t think one is especially clearer than the other. At least “type” has the advantage that users are familiar with it from browsers, so it’s easier to remember.

I see the logic in that if we call something “format,” it would make sense that it doesn’t behave similarly to browsers. The problem here though is that whatever we call the flag, it should behave similarly to browsers. That’s what users will expect, even if the flag is --entry-format or --input-format or whatever. The proposal for --type had it behaving as what I’m currently calling --package-type: it was meant to apply to the entire package scope, not just the initial entry point file. (--type=auto makes no sense otherwise; it was always meant to detect the type from the entry point, and apply that to the entire scope.) The fact that --type only applied to entry points was a bug, that we tried to correct but people objected.

I think the real problem here is that users expect the --package-type behavior, so if we have any flag at all it should behave that way. We can rename --input-type to make it clearer that it doesn’t behave similarly to package.json type, but then we risk a different kind of user confusion in that why is "module" sometimes called a type and other times a format. I don’t think we should rename the "type" field because it does behave like browsers, and like users expect; that’s why I think it’s such a good name.

[devsnek]

I think the issue here is that these flags are too generalized and ambiguous to be given a name or behaviour anyone will agree on. I think it would really be in our interest to consider a more structured design for declaring the formats of files, and leave the flags solely for inputs with no file (stdin and --eval)

[bmeck]

@GeoffreyBooth
I cannot think of how they would act the same, they are doing different things. What do you mean that they should act the same? In the browser, type=module is defining which script system the resource is loaded under. This behavior becoming analogous in node would be like a package changing any require into an import and any import into a require, but that doesn't make sense regarding file extensions nor when the person importing a module somehow doesn't use ESM. Also, if they are treated as synonymous it would be better to take the less overloaded term.

[ljharb]

tbh that’s an argument against “type” because node simply won’t behave completely similar to browsers. since it’s different, a term that implies difference seems better.

[GeoffreyBooth]

In browser world, when a user has <script src="/app.js"> and they add type="module" to it, the effect is that app.js is loaded as ESM (and so are any files imported from app.js). The same happens when "type": "module" is added to package.json—it’s the user telling the runtime to load the .js files within as ESM. From the user’s perspective, both type="module" and "type": "module" enable ESM mode for .js files. Obviously Node and browsers have various differences under the hood, but from users’ perspective the two types behave similarly enough that I think it’s better UX for them to share the same name.

[bmeck]

While the two do allow a desired use case of .js usage, they do so through very different mechanisms being configured. We shouldn't be saying that different mechanisms should be called the same because the have an overlapping use case. If that is the case, I would state it is even more important to not use "type" than I previously thought. Naming based upon use case worries me since it hides what mechanisms are being used intentionally by prioritizing a name in a use case overlap between different environments using different mechanisms. It hints that the different mechanisms are interchangeable even when the mechanisms are not. I find the leaning on hiding what is being done not fatal, but intentionally doing so to trick something to look like a different mechanism to be fatal to myself.

[SMotaal]

I think that if we consider the abstract process of resolving a module from a package we might get a more intuitive feel (for or against) for how type fits here.

1. Somehow I need module from package.
2. Node locates a likely package.json somehow.
3. It verifies This potentially implies { name = "package" }.
4. It then determines how it will load module from this package by checking the { type } field of the package.

If we cut out all noise, imho, it is a very coherent narrative and as far as the field name "type" goes, I am reluctant to doubt that it is one of the better options we have.

As for flags, I personally was a little reluctant when I first heard --type but once we decided to go in that direction, I find that the more verbose suggestions (ie --input-type et al) might be less fitting in such a critical flag — it is not a flag for trimmings or optimizations, it is the flag that will either let your code run (correctly or at all) or not :)

[ljharb]

I don’t think the steps work like that; the name leads to the package.json, the name field doesn’t have to match or even exist afaik.

[SMotaal]

@ljharb I realize (separate point but absolutely true no doubt) that this a little artificial, but generally it is implied that a validly named package would be correctly placed where it would be found respective to its { name } in many or more cases — I am being very abstract (as always)

Made a little edit nonetheless 👍

[bmeck]

With this being rolled out already, and not having public comparison to browsers working the same way/confusion on the meaning (in our docs or in the feedback I've been reading about the term "type"); I think we can close this. I do not see the benefits of the naming change being sufficient to warrant conflict if my main concern over the term is not appearing in the wild. We can readdress at a future date if the concern does arise again.