What makes a parameter optional?

[Josh-Cena]

Quick question: what does it mean when we mark a parameter as {{optional_inline}}?

1. It doesn't throw when you omit it (e.g. all parameters are force-casted to strings so omitting it is the same as passing in "undefined")? In this sense, the searchString of String.prototype.includes() would be optional
2. The program has a somewhat sane behavior when omitted, e.g. doesn't display the string "undefined" literally, but the algorithm can be described with or without the mention of optionalness? In this sense, the value of Set.prototype.has() would be optional
3. It has a special behavior when undefined is passed in, e.g. it gets converted to "" instead of "undefined"? In this sense, the separator of String.prototype.split() is optional
4. It has a special behavior when omitted compared to when an explicit undefined is passed in?

Hopefully no one says (1) or (4) so it's really a two-choice question. I'm also open to other interpretations. E.g. all interpretations above are based on behavior, but we may also look at what the spec marks as optional (in square brackets), or what fn.length gives. However, these give unintuitive results as well—for example, the spec thinks the compareFn of Array.prototype.sort() is not optional.

A natural follow-up is: can an optional parameter be followed by a non-optional one, if we managed to rigorously define optionalness?

[wbamberg]

Usually I think of optional in terms of (1). You don't have to pass it, and there's a default documented behavior if you don't. If we adopted (1), would there be a lot of counterintuitive results in the JS docs?

(2) sounds all right as well though, depending on what "somewhat sane" means. From your example I think it would be fine to consider the argument in Set.prototype.has() as non-optional.

As for (3), I think, in your example of String.prototype.split(), separator is clearly optional - the page even documents what happens if you omit separator, and the interactive example even omits it.

A natural follow-up is: can an optional parameter be followed by a non-optional one, if we managed to rigorously define optionalness?

Do you have interesting examples here too?

[Josh-Cena]

So first, these options form a gradient: a parameter that's type-3 optional must be type-2 and type-1, a parameter that's type-2 optional must be type-1 optional, etc.

If we adopted (1), would there be a lot of counterintuitive results in the JS docs?

Yes, there is. This would make literally all parameters optional. I'm not aware of many places where the language throws when undefined is passed. For example, searchString in String.prototype.includes() is explicitly said to be non-optional, because omitting it would cause the method to search for the string "undefined", which is very unlikely to be intentional. This definition is probably more suitable for web APIs.

(2) sounds all right as well though, depending on what "somewhat sane" means

"Somewhat sane" generally means undefined doesn't get coerced to NaN or "undefined", but has the same behavior when an explicit undefined is passed.

I think it would be fine to consider the argument in Set.prototype.has() as non-optional.

That contradicts the principle, though. Set.prototype.has(), when passed no parameters, searches for the element undefined, which is "sane" because has(undefined) is legal and well-defined.

(3) is basically our current approach, so of course most of our existing docs are conformant. However, because undefined always gets coerced to 0 when used in an integer context, sometimes we treat those parameters as "optional" as well, while in this case it's more type-2 instead of type-3 optional.

Do you have interesting examples here too?

Not many that I'm aware of. I think the JS API design is currently good enough to prevent this situation under most definitions of optional.

[wbamberg]

So first, these options form a gradient: a parameter that's type-3 optional must be type-2 and type-1, a parameter that's type-2 optional must be type-1 optional, etc.

If we adopted (1), would there be a lot of counterintuitive results in the JS docs?

Yes, there is. This would make literally all parameters optional.

Well let's not do that then! That seems likely to commit us to different definitions for JS and Web/API already, right? and at that point maybe we should only consider https://github.com/orgs/mdn/discussions/452 for Web/API.

I think it would be fine to consider the argument in Set.prototype.has() as non-optional.

That contradicts the principle, though. Set.prototype.has(), when passed no parameters, searches for the element undefined, which is "sane" because has(undefined) is legal and well-defined.

Sorry, I think I meant "optional" for has().