Why options over multiple methods? e.g. `Object.keyCount`

[SukkaW]

• Object.keyCount or Object.ownKeyCount
• Object.ownPropertyCount
• Object.ownPropertySymbolCount

This aligns with existing Object methods and is easy to understand.

[ljharb]

That is definitely an alternative API direction - but engines have expressed a lot of hesitation about method count, meaning that they seem to strongly prefer fewer methods than more. We'll suss that out before stage 2.7, of course, and if the committee prefers separate methods then that's fine.

[SukkaW]

The main concern/argument is that the options will still create an intermediate object (even objects if there is an array in the options). Considering this:

for (let i = 0, len = objectPool.length; i < len; i++) {
  const count = Object.propertyCount(objPool[i], { keyTypes: ['stringIndex', 'noStringIndex'] });
  // Two intermediate objects are still being created constantly.
  // And no, nobody will ever think of hoisting the options. Irony of JavaScript performance.
}

For engines with slow GC implementation (for instance, SpiderMonkey), this would become an overhead.

And the second concern/argument would be the learning curve. Having new methods aligning with existing methods will help understanding.

[BridgeAR]

For engines with slow GC implementation (for instance, SpiderMonkey), this would become an overhead.

That is correct while it should still be significantly faster than the current situation. The cases where the default is not needed are rarer and more costly anyway right now, so the benefit should still be really big in all of that cases.

[...] the learning curve. Having new methods aligning with existing methods will help understanding.

Refs: https://github.com/ljharb/proposal-object-property-count#alternatives-considered

I actually argue that it's the other way around. From my experience the biggest challenge is that someone gets to know a method in the first place. As soon as that's the case, options will also be looked at. But even if that's not the case: anyone who really cares about performance will look for such method and its options.

The API is designed to be easy to understand. The options however would always be for someone with a deeper level of JS knowledge. The reason is that most developers don't know what an enumerable / non-enumerable, index vs non index string property or even a symbol is. Making the API friendly for the average developer while also making it good to use for experts who can leverage it even more seems good to me.

All that said: I agree with @ljharb that the semantics do not matter all that much. The API will be found and used who really cares about it in the end, no matter how it looks like.

[SukkaW]

The cases where the default is not needed are rarer and more costly anyway right now, so the benefit should still be huge in all of those cases.

IMHO, the standard should always provide space for engines to optimize later if they want to. If the options might require creating two or more intermediate objects, engines can't optimize this. Currently, there are no ECMAScript built-in methods/API other than Object.defineProperties that accept nested object(s) as options.

IMHO, the options should not create nested objects.

The API is designed to be easy to understand. The options however would always be for someone with a deeper level of JS knowledge. The reason is that most developers don't know what an enumerable / non-enumerable, index vs non index string property or even a symbol is. Making the API friendly for the average developer while also making it good to use for experts who can leverage it even more seems good to me.

I would still argue that. Yes, we have Object.keys in the ECMAScript, but we also have Object.getOwnPropertyNames and Object.getOwnPropertySymbols in the ECMAScript. The latter two methods were introduced to the ECMAScript way later than the Object.keys. You still need to be a JavaScript magician to use the latter two methods, but at least they are still easy to learn, as they only accept an object without any options. And also Object.getOwnPropertyDescriptors, it doesn't accept any options about filtering the key anyway.

Also, having fewer options or even no options means there will be less "branching" inside the engine implementation, which would potentially improve the performance by making fewer branch predictions. Doing fewer jobs is always better than doing more jobs, no matter the job has already been optimized.

Since this API will be used in many hot paths (as shown in proposal examples), this should be carefully considered.

[ljharb]

Currently, there are no ECMAScript built-in methods/API other than Object.defineProperties that accept nested object(s) as options.

There's a ton in Intl, and there's a ton coming to 262 - the base64 proposal, Temporal, and a number of others. Engines have not indicated any concern about options bags.

[BridgeAR]

If I recall the last TC39 meeting where this was discussed correct, this did not come up as a concern. I suggest we close this as resolved, if that's fine @SukkaW?

[bakkot]

I didn't go into this because it was only going for stage 1, whereas this is a stage 2 concern, and because I'm not convinced by the need for anything other than the very basic use case at all. But if we're going to support multiple use cases I'd still lean towards having separate methods. So I would not like to consider this resolved.

[SukkaW]

I'd still lean towards having separate methods

Would you like to address the reasons briefly behind your preferences here?

For me, I bring this up just because this would align with existing Object static methods, and would have simpler (and neater) options (if an option were ever needed).

[bakkot]

I agree with the point about aligning with existing Object static methods. Also, I think separate methods are more discoverable than options bags. Sometimes it's not practical to cover the full API surface without options bags - for example, I wouldn't have separate methods for counting enumerable vs non-enumerable properties - but when there's a straightforward way to have a small number of reasonably distinct methods instead of having options bags I will generally prefer that for discoverability.