MutationObserver spec defines options as optional, which is inconsistent with actual behaviour

[stroiman]

This is probably the wrong place to report, as it's more something that appears to be wrong or inconsistent in the IDL standards.

The MutationObserver is defines the options as optional for the observe operation:

// Source: DOM Standard (https://dom.spec.whatwg.org/)
[Exposed=Window]
interface MutationObserver {
  constructor(MutationCallback callback);

  undefined observe(Node target, optional MutationObserverInit options = {});
  undefined disconnect();
  sequence<MutationRecord> takeRecords();
};

However, according to MDN documentation for the options

An object providing options that describe which DOM mutations should be reported to mutationObserver's callback. At a minimum, one of childList, attributes, and/or characterData must be true when you call observe(). Otherwise, a TypeError exception will be thrown.

So options aren't optional according to that documentation.

And indeed, running the following in a JS console in a browser (this was executed in Firefox)

o = new MutationObserver(() => {})
o.observe(document.body) 

Uncaught TypeError: MutationObserver.observe: One of 'childList', 'attributes', 'characterData' must not be false.
    <anonymous> debugger eval code:1

So it appears to me that options should not be optional.

[tidoust]

The optional keyword and default value are imposed by Web IDL in §2.5.3:

If the type of an argument is a dictionary type [...], and that dictionary type and its ancestors have no required members, and the argument is either the final argument or is followed only by optional arguments, then the argument must be specified as optional and have a default value provided.

The underlying problem is that there is no way in Web IDL to express the constraint "no single member is required for this dictionary argument, but one of the members must be set". That constraint needs to be defined in prose instead (the TypeError is thrown according to step 3 in the observe() algorithm).

In short, you're right that options argument is not optional in practice, but Web IDL is not expressive enough to handle it out of the box. Looking at the Web IDL repository, I see that whatwg/webidl#903 proposes to extend Web IDL to cover this use case. The issue mentions... MutationObserver.observe() as an example ;)

[stroiman]

Hey, thanks for the detailed reply.

What a coincidence 😆

I'll adapt in my own code generation, and close this "issue", and keep an eye on the mentioned, though the timeline doesn't seem to indicate that it's a high priority.