MediaQueryList.prototype.addListener & removeListener are marked as deprecated

[fabiancook]

TypeScript Version: master

Search Terms:

MediaQueryList addListener
addListener
MediaQueryList

Code

const listener = window.matchMedia("(max-width: 1000px)");
const handler = () => {};
listener.addListener(handler);
listener.removeListener(handler);

Expected behavior:

addListener and removeListener are "valid" signatures to invoke

Actual behavior:

addListener and removeListener are deprecated

Playground Link:
https://www.typescriptlang.org/play/#code/MYewdgzgLgBANgS2gUzMgTjAvDA7gsAExFwDoBbAQymAAsBZZQhSgCgCJWqAPAWn0JRaALhgBGAAxSADtwCU7OQG4AUKEixalInAzYYrOdgB8MAN4BfVYhRp0pSoUIAZJFFQZWWnRmUqb7nak6MjkIABuyK62nt6EuujKQA

Related Issues:
None

Notes:
This document describes the MediaQueryList interface: https://drafts.csswg.org/cssom-view/#dom-mediaquerylist-addlistener

It doesn't list addListener and removeListener as deprecated, does not give an indication that they will be deprecated in the future, it also does not say that you should use addEventListener and removeEventListener instead.

It did say that addListener and removeListener are direct aliases.

Source:
https://github.com/microsoft/TypeScript/blob/master/lib/lib.dom.d.ts#L10018

Why would I bring this up:

Because Safari and Internet Explorer do not support addEventListener and removeEventListener, but they do support addListener and removeListener.

Because addListener and removeListener are deprecated it means that people are more likely to use the alternatives without looking at the issues with doing so.

A lot of examples with the usage of MediaQueryList show addListener and removeListener usage, even the documentation on MDN: https://developer.mozilla.org/en-US/docs/Web/API/MediaQueryList#Examples

[Maxim-Mazurok]

I agree, this change created a bit of trouble here: ReactTraining/react-media#135 (comment)
Potentially, breaking compatibility of the popular React library.
Luckily, I decided to go with my custom solution and not using this library, and later doing cross-browser testing I've found out that Safari doesn't support addEventListener for MediaQueryList. Even 13.1 (TP).

[Maxim-Mazurok]

BTW, the best way to see the browser support for these particular methods is to go to MDN:MediaQueryList#Browser_compatibility and check out MediaQueryList inheriting from EventTarget section of the table. Thanks to mdn/browser-compat-data#3674 for making this contribution.

[chaoyangnz]

I have to say, due to the label with deprecated, I triggered an incident in our production.
IT IS TOTALLY MISLEADING!

It is still using and available in every green browser. It is NOT deprecated.

[polarathene]

@chaoyangnz

A deprecated API is one that you are no longer recommended to use, due to changes in the API. While deprecated classes, methods, and fields are still implemented, they may be removed in future implementations, so you should not use them in new code, and if possible rewrite old code not to use them.

How is deprecation misleading? It's available, it probably works, but you shouldn't rely on that to continue to be the case going forward. You're advised to use a replacement where possible, deprecation does not mean no longer available.

[Maxim-Mazurok]

By the way, Safari technology preview version has support for this new API.

[robertn702]

@polarathene

How is deprecation misleading? It's available, it probably works, but you shouldn't rely on that to continue to be the case going forward. You're advised to use a replacement where possible, deprecation does not mean no longer available.

If something is deprecated, it means that it should not be used. You're correct when saying that "deprecation does not mean no longer available", but it's misleading to say it should not be used right now. This is especially true when it HAS to be used on a major browser like Safari. Instead, this should be a warning of future deprecation until the the method is widely supported on major browsers.

Example
In VSCode, this is a pretty strong visual indication that I should change the method immediately. I would not expect changing to the recommended method to completely break my app on all iOS devices, which it does.

[polarathene]

it's misleading to say it should not be used right now.

I haven't said that? I advised to use the newer API where possible and to not rely on a deprecated API. Deprecations can exist for quite some time before they're dropped, they're given as a heads-up to adopt the newer API before the deprecated one ends up no longer supported.

In this case, deprecations within the browser can take quite a while to be completely replaced, and may still stick around for some form of compatibility. Not only that, we're developing for multiple clients, each with multiple versions, so that deprecation can be true / valid in some clients, and others that are late to adopting the deprecation (by providing a new API you can use instead) obviously add friction to that.

The latest Safari for macOS apparently supports the newer API now, so it's only a matter of time until iOS catches up with that and this issue itself will lose relevance debating it. That said I acknowledge / agree that there doesn't appear to be any official "deprecation", just encouragement to use the newer API, the older one will apparently remain, perhaps with some minor perf drawback that isn't likely to affect anyone in practice.

---

I handle this with a conditional in a PR:

const mql = window.matchMedia(v.media)
if (mql.addEventListener) {
  mql.addEventListener(`change`, this.handleVariantChange)
} else {
// Deprecated 'MediaQueryList' API, <Safari 14, IE, <Edge 16
  mql.addListener(this.handleVariantChange)
}

My "deprecated" comment for MediaQueryListListener(note, modern browsers alias this for now) is not quite correct, MDN encourages using the newer standard event mechanism, the older non-standard API is kept by browsers for backward compatibility. A newer version of Safari that's to be released this year will also support the newer API. MDN browser compatibility

If you rather just use addListener() there's probably nothing to be concerned about, I don't use TypeScript, so I've never even seen that UX issue in your screenshot. I can see how that'd be problematic and you do raise a valid case.

TypeScript handling it that way is probably with the intent to direct developers to the newer API, but the dev places too much trust in TypeScript without looking into the why and just assumes it's a 1:1 replacement without needing to worry about browser wide support? How does it handle features that don't usually have widespread support available? Does it protect you from that too, or is the developer meant to be aware of such themselves?

---

Instead, this should be a warning of future deprecation until the the method is widely supported on major browsers.

If that's something TypeScript supports, absolutely, that sounds much better 👍

[Maxim-Mazurok]

AFAIK, there's no such thing as "soft deprecation" in TypeScript / JSDoc. Something is either deprecated or not.

If it stays deprecated - there's a risk that devs will follow this suggestion blindly.

If we make it not deprecated - there's a risk that devs will keep using the old API and then will encounter some issue. I don't think that it will be removed soon, because it's not even deprecated yet. So, the risk is quite tolerable. Another downside form the dev standpoint is that it'll be harder to decide which API to use, and this deprecation helps dev to make choice in favor of the new API.

That being said, I think that some comment should be added to this JSDoc, explaining that this method is not actually deprecated and is still the only option is some browsers.

This comment can be added by keeping the method deprecated, in this case, curious dev will go to the definition and see this comment.
If we add this comment and remove deprecation - curious dev that explores available methods, trying to understand which one to use, will also see this comment and make the right decision. This case is less likely, IMO.

Considering that usage of deprecated methods may trigger some unnecessary static code analysis warnings, it's probably worth replacing deprecation notice with an explanation comment.

On the other hand, keeping it deprecated (with the comment) will promote new API adoption, which is probably a good thing (and will also push other browsers to add new API support).

So, it's a quite hard choice. If I had to choose right now, I probably would leave it deprecated, because the new API is about to get support in all major browsers.