New APIs added to lib.d.ts may break client codes. Allow duplicated members in interfaces? Make lib.d.ts overridable?

[duanyao]

I noticed that recently a lot of new APIs are added to lib.d.ts. Of cause this is a good thing, however my code breaks badly because of such update.

Previously I had added a lot of declarations in my code for HTML5 APIs that were missing in lib.d.ts . Now some of them are added to lib.d.ts, and I get quite a few "duplicated identifier" errors. For example, I had added this piece to play with fullscreen:

interface Document {
//...
  fullscreenEnabled: boolean;
  mozFullScreenEnabled: boolean;
  webkitFullscreenEnabled: boolean;
}

Now fullscreenEnabled and webkitFullscreenEnabled are available in lib.d.ts, and my code breaks, and I have to remove them. However, you are still missing mozFullScreenEnabled right? -- well, waiting for the next break.

Web platforms are constantly evolving, it is not practical to expect lib.d.ts always up to date, so developers just have to write such compensating declarations from time to time. Can TS avoid such breaks? I have a few ideas:

• Allow duplicated members in multiple interface declarations, as long as they are identical. In the fullscreen API example above, tsc should not fire errors. Optional compiling warnings are acceptable, to assist developers to remove redundant codes at convenient time.
• Make lib.d.ts overridable. When tsc find conflictions between lib.d.ts and client codes, it should pickup declarations in client codes. This is because declarations lib.d.ts may contain bugs, developers should be allowed to workaround them. E.g. MutationObserver's constructor was missing a parameter for a long time. Again, optional warnings are welcomed.

What do you think?

[kitsonk]

Interfaces are open-ended... Once you strip out the collisions, you will only be left with the "extensions" to the interface you are making. For example, this is perfectly valid TypeScript:

interface Foo {
    bar: boolean;
}

interface Foo {
    qat: boolean;
}

var foo: Foo = {
    bar: false,
    qat: true
};

[duanyao]

Interfaces are open-ended -- I known.
The problem is: why should duplicated members in multiple parts of an interface be treated as error? I think duplications are perfectly legal if an interface is developed/maintained by multiple parties independently.

Web APIs is a good example. Different browser vendors implement their own set of APIs. Largely the same, but have many small differences, e.g. vendor-prefixed APIs . Currently, TS's lib.d.ts is based on IE's API, this is obviously limited. Ideally, every browser vendors should provide their own version of lib.d.ts, and developers can include some or all of them to achieve cross-platform-ness. An imaginary client code looks like:

///<reference path='lib.ms.d.ts'/>
///<reference path='lib.webkit.d.ts'/>
///<reference path='lib.blink.d.ts'/>
///<reference path='lib.moz.d.ts'/>

var requestFullscreen = document.requestFullscreen || 
  document.mozRequestFullScreendocument || document.webkitRequestFullscreen || 
  document.msRequestFullscreen;
//...

But obviously this can't be done with current TS, because those lib.nnn.d.ts files contain large amount of duplicated members of interfaces.

[RyanCavanaugh]

This is can be a giant pain. We should try to figure something out.

[basarat]

Make lib.d.ts overridable. When tsc find conflictions between lib.d.ts and client codes, it should pickup declarations in client codes.

FWIW this is allowed when compiling with --nolib flag.

Feel like recommending that lib.d.ts be removed from core and spinned into an external project maintained by MS + community.

[duanyao]

FWIW this is allowed when compiling with --nolib flag.

No, I just want to override the conflicting pieces, not lib.d.ts entirely. Maintaining a whole lib.d.ts myself is not practical (and there are lib.d.ts used by IDEs).

Feel like recommending that lib.d.ts be removed from core and spinned into an external project maintained by MS + community.

Good idea. However it is still nice to allow duplication/overriding of declarations, because there is still no guarantee that individual parties that maintaining those declarations keep in sync with each other.

[alexeagle]

Another use case for this: if a project wants to target both ES5 and ES6, they have to include polyfill declarations for ES5 emit (eg. Promise) but change the build to remove these for ES6 emit. It would be easier if both es6-promise.d.ts and lib.es6.d.ts could be present to the compiler, so long as they don't conflict.

[ENikS]

There should be no harm in multiple declarations of the same interface as long as there are no conflicts.
Another option would be conditional compile, something along these lines:
#ifdef Promise
...
#elseif
...
#endif
This needs to be resolved soon, it is getting really painful to target both es-5 and es-6

[mhegazy]

This needs to be resolved soon, it is getting really painful to target both es-5 and es-6

What is wrong with just including lib.es6.d.ts in your project? the library is a super set of ES5 one, and if your project targets both, and you have the correct pollyfils, then you should be safe.

[ENikS]

I have two different node packages defining Iterable and IEnumerable interfaces. Including lib.es6.d.ts would not solve that problem because it also defines Iterable.
How about these who will add *.d.ts of my package? I can not require them do add lib.es6.d.ts as well.
What is wrong with ignoring duplicates?

[duanyao]

This issue also affects DefinitelyTyped potentially. Currently there are definations for webrtc, web speech, web midi, and firefox/chrome specific apis, etc, which will confilict with future TS releases. It is even harder for web developers to resolve such conflicts. One can't simply drop DefinitelyTyped because lib.d.ts doesn't contains all vendor prefixed APIs.

I think ideally switching ES5/ES6 targets should not involve changing lib.d.ts, and "compatibility note" suggested in #3250 is a better alternative. There are some ES7 APIs to be added to TS soon, do we want yet another lib.es7.d.ts?