Repository navigation
[Web API type definition issue] lib.dom options parameter for MutationObserver#observe should not be optional #2566
Description
Summary
Not passing options, or passing options without minimum requirements, is an error (type error at runtime)
Expected vs. Actual Behavior
Expected:
Calling new MutationObserver(fn).observe(el) without a second options argument should show a type error because options are required.
Actual:
There is no type error. We discover the error at runtime.
Playground Link
Browser Support
- This API is supported in at least two major browser engines (not two Chromium-based browsers).
Have Tried The Latest Releases
- This issue applies to the latest release of TypeScript.
- This issue applies to the latest release of
@types/web.
Additional Context
From MDN docs:
An object providing options that describe which DOM mutations should be reported to
mutationObserver's callback. At a minimum, one ofchildList,attributes, and/orcharacterDatamust betruewhen you callobserve(). Otherwise, aTypeErrorexception will be thrown.
Activity
saschanaz commentedon Oct 7, 2026
Looks like this is only marked optional because webidl can't represent complex member dependency.
saschanaz commentedon Oct 7, 2026
But I'm not sure TypeScript can represent "pass one member at least" kind of type either?
MartinFerret commentedon Nov 1, 2026
TypeScript could express "at least one of" with a union, but I don't think it's worth it here. Either
MutationObserverInititself becomes a union, which breaksinterface X extends MutationObserverInitand building the options object incrementally, or the parameter gets a separate union type, and then values typed as the existing all-optionalMutationObserverInitare no longer assignable. It would also need to model the implicit rules, whereattributeOldValueorattributeFilterenableattributes, andcharacterDataOldValueenablescharacterData.A minimal and safe improvement would be to make
optionsrequired. Per the DOM spec,observe()throws aTypeErrorwhenever none ofchildList,attributesorcharacterDataends up true, so callingobserve(target)without options always throws (this is also covered by WPT indom/nodes/MutationObserver-sanity.html). Making the parameter required would flag that mistake at compile time without affecting code that works at runtime.Would a PR doing just that be welcome? I'd be happy to open it.
saschanaz commentedon Nov 1, 2026
We can start with that, yes.