Split official "lib.t.ts" into different files / Special references clauses

Topics: General, Language Specification
Apr 27, 2013 at 3:44 PM
Currently, lib.d.ts has too many things that shouldn't be there or there should be an option to include. By that I mean the sections:
  • IE10 ECMAScript Extensions
  • IE9 DOM APIs
  • IE10 DOM APIs
  • Windows Script Host APIS
Basically, everything that is not "core javascript api available to most browsers" should not be there. I believe this causes some problems as someone developing depending on the IDE can accidentally use a method that is not generally available in other browsers.

I know that the nature of javascript is dynamic and in the end this could happen to any method, not only those IE specific, but I think you get the point.

An idea to solve this would be to split the lib.d into multiple files, and allow for a special <references /> clause that would include the definitions.

So, imagine that you split the lib.d.ts into:
  • js.d.ts (only the core of javascript, curently most of lib.d.ts)
  • ie.d.ts
  • wsh.d.ts
  • etc
That brings us to the references tag. This tag would work just like today references, but instead of:

/// <reference path="~/lib.d.ts" />

could be something like:

/// <reference def="@/lib.d.ts" />

The @, just like the ~ would make a relative path to some special folder.

I suggest these folders would be searched in the following order:
  • Project specific "definitions folder" (eg. ~/Scripts/Definitions, preferably customizable)
  • Typescript extension folder (current home of lib.d.ts)
So, creating a blank typescript file would be the same as adding a line like this at the top of the file:

/// <reference path="@/lib.d.ts" />

which in turn would be a small file with a couple of <references /> tags to the other "core, ie, wsh", etc in the same order are they are in the file today, maintaining backward compatibility.

But if you add a references line to your file using the @ syntax, the compiler wouldn't add the default one and let the user choose the specific definitions it would include. (An alternative to this flow would be to have a specific tag like "<reference clear='true' />" or similar to remove any default references).

This would greatly improve the code completion for projects for node.js, browser extensions and even web pages that don't want to use the IE extensions by default, but restrict the development to general available JS, so you get build errors if you try to go out of the desired scope.

Also, as a bonus of this method, people could have their own "lib.d.ts" in the project's definition folder, so they could have a "default reference" for all project files without having to add the <references /> line to each file, as the compiler would just use the first lib.d.ts that it finds using the default reference it adds to "@/lib.d.ts". A lib.d.ts for a chrome extension could look like this:

<references path="js.d.ts" />
<references path="chrome.d.ts" />
<references path="jquery2.d.ts" />

And all files in the current project would just have that by default.

What do you think?
Apr 29, 2013 at 5:05 PM
We've talked about doing this a few times. There are some options here.

lib.d.ts does have some IE-specific stuff, largely because it gets autogenerated from IDLs we have, but really most of it is DOM and JS api. For non-web platforms, like Node.js, we wouldn't want to spend time parsing the DOM elements.

I'm going to add this to our feature recommendations to remind me to explore cleaner approaches going forward.
Apr 29, 2013 at 5:05 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.