Only use exceptions/promise rejections for exceptional situations

[domenic]

Related to #3, but seems separate. You should not throw an exception, or analogously return a rejected promise, in mainline scenarios. Instead you should provide a non-throwing/rejecting function which returns a sync value or fulfilled promise explaining how to avoid the error cases.

In particular, something named "play()" could return a rejection if playing cannot happen. But something named "canAutoplay()" should only return a boolean; it should never throw/reject. (Except perhaps in cases of weird hardware failure??)

[mounirlamouri]

If I understand correctly, you would recommend that canAutoplay() is resolved with a boolean that says whether it can autoplay and rejects only in the case where the current state does not allow us to answer the question (ie. no metadata)?

[domenic]

Yeah, that sounds right to me, assuming it is exceptional for there to be no metadata.

[mounirlamouri]

Not having metadata isn't rare, it just depends how the media element is setup. The idea here is that the call would require this (as a "contract") and not being in this state would fail. I believe it's something that other HTML elements do such as HTMLInputElement that throws when some properties are used when not set to a certain type.

[domenic]

Oh, no, in that case, I would suggest a tri-state return value, e.g. "unknown", "yes", "no" or similar.

We did used to have some input element stuff about selection that would throw when used in the wrong state, but that violated this design principle and so we changed it to return null. whatwg/html#1006 and whatwg/html#2327

[mounirlamouri]

I think a tri-state would make things harder. It was our initial idea but it's very easy to do the wrong thing when using a real tri-state (not a DOMString?) as the third state will either have to be designed to look like true or false. Neither is ideal.

Though, I would like to discuss this "design principle". Design by contract is a fairly common software pattern design and this really helps in this situation. I think this is really the best solution for our problem here. Furthermore, we already have many promises throwing that are not exceptional cases. For example, play() throws when playback isn't allowed because of autoplay and this isn't very exceptional. Similarly, a lot of APIs throw if permissions wasn't granted by the user. This case is much more deterministic because the page has full control of the state of the element and would only need to know that this API requires the element to be in a given state in order to be used.