On TypeScript Definitions... We Have A Problem!

Topics: General
Oct 16, 2012 at 6:24 AM

On TypeScript Definitions... (and 3rd Party JS libraries such as knockoutjs, expressjs, etc)...

I'm finding that it's a mess out in the wild... This project (https://github.com/borisyankov/DefinitelyTyped) hopes to bring things together, but there is a fundamental flaw in this approach... Firstly it's a project not a portal, and second, there is no version correlation between the published library and the definition file. I've raised the latter as an issue here: https://github.com/borisyankov/DefinitelyTyped/issues/2

This needs to be addressed by MS fast and a coordinated open source repository needs to be set up, much like npmjs.org (not NuGet because that is MS specific) so that people can contribute the definitions in one place...

For now, however, it is quite difficult to figure out what version of a library a definition refers to. For example have a look at the express.d.ts in the (DefinitelyTyped) project. This was copied from the MS samples but defines the 2.x express lib. We use the 3.x version... Also, there are at least 3 variants for the knockoutjs d.ts all of which define the library differently!

So... making sure we are using the correct/best defined d.ts is taking time!!!

Coordinator
Oct 16, 2012 at 4:18 PM

I couldn't agree more.  We're actively working on a solution to this now.  Like you said, we need a one-stop way to find definitions, coordinate (so we can hopefully avoid having many versions of typings for the same library), and make it clear what versions of a library are supported.  Until this is in place, working with projects like DefinitelyTyped in the interim may help at least make it easier to track down declare files and contribute fixes.

I'm going to move this to an feature request in the issue tracker.  We can use that to brainstorm features this service should have.

Coordinator
Oct 16, 2012 at 4:18 PM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.
Oct 17, 2012 at 5:11 PM

Jon, would you elaborate a bit on this 'We're actively working on a solution to this now. '

I was thinking on creating a web site, similar to nuget, but feeded with definitions from DefinitelyScripted. No point to start, if you are doing something already?!?

Oct 18, 2012 at 2:59 PM

@borisyankov, I like your site repository.... but it does not solve the problem completely nor would a site with just type definitions.

I feel there is a more fundamental problem to which I elaborate here.
I will post the comment here again because I feel it is extremely important to catch this early!

There are a number of considerations to take into account for file name versioning that points to abstracting module dependencies. For example the express.d.ts from the MS sample includes a reference to node.d.ts at the head of the file which introduces an implied dependency between the express.d.ts and node.d.ts.

Adding version numbering to the file names, for example a reference to node.0.8.x.d.ts in the header of an express.3.x.d.ts would create a 'hard' dependency to a specific version of the nodejs definition.

Nodejs uses package.json files with a 'dependencies' entry that has a very nice/flexible way of expressing dependency versions. Something like that for definitions may work be great...

// Note that 'path' was removed because the source of the dependency may not reside in a fixed location for all use cases
//<reference module='node' ver='>=0.8.0' /> 
//<reference module='express' ver='3.x' />
//<reference module='underscore' src='https://github.com/alvivi/typescript-underscore/blob/master/underscore.d.ts' />

The above means that the compiler would need to probe known locations to resolve .d.ts files that match the criteria in the reference directives.  The Node Package Manager (npm) does this so I'm sure the TypeScript engine or an extension could be made do this too.

Oct 18, 2012 at 3:46 PM

I agree completely.

On the versioning side, waiting on the TypeScript team to think of a better solution, something like what you suggest would work much better.

On the 'community site' side, my idea was in addition to the site itself, that it would be a Nuget repository. This would work perfectly for Visual Studio developers. You are correct though, that not everyone uses it, nor develops on Windows.

Coordinator
Oct 19, 2012 at 4:59 PM

It sounds like we're moving in the same direction (and it makes sense to talk about what we're thinking, too).  Ultimately, a service like npm or nuget would be ideal.  Let people search for the declare files they need and let the tool grab whatever dependencies they have (whether other declare files or optionally the .js files themselves)

Going along with AnotherWay's suggestion, having a file like the npm package.json for each declare file would be helpful.  It's also something that future services could use.  Our version of a package.json might have:

  • The name of the package
  • A list of dependencies, if any, of this package
  • The name of the library being wrapped
  • The url to the library (and version) being wrapped
  • The version of the current wrapper
  • The version of the library being wrapped
  • The version of TypeScript used in wrapping

I like how you can describe multiple things in the npm version, like a dependency and a required version, or an external dependency and its location, so maybe some of those bullets could be merged.

Oct 22, 2012 at 5:42 AM

Great to see things are moving in that direction!

I trust there will be some quality control by the owners of such a service.  What we are seeing is very different ways to define the same .d.ts file for the exact same external library.  I guess this will settle down as people find the preferred way to make these definitions.

Having a solid source of definition files would, in my opinion, be a huge factor in TypeScript's adoption in the community!

Apr 2, 2013 at 4:08 PM
On this topic, I posted a suggestion to move the DefinitelyTyped defniitions to Bower: https://github.com/borisyankov/DefinitelyTyped/issues/428

This keeps the definitions in GitHub and leverages (what's becoming) a standard client side package manager for JS.
  • I can specify a dependency on a specific version
  • I can keep the branches in sync between the TS repo and the library repo
  • I can provide additional TS specific documentation in a README.md and point back to the original documentation
  • I can also include a bower update in my web deployment script to pull down the dependent components rather than check them into the application's repo (I did this for Azure Git Deploy).
  • Plus, this repo can still act as the container for TS declaration files by setting up a submodule to the above repo.
I tried this out with the hammerjs library, calling the Bower package 'hammerjs-ts'. Pulling in this declarations file will also pull in the hammerjs library as a dependency. We probably need a package naming convention for TypeScript declarations.
Jul 11, 2013 at 5:19 AM
A related discussion that touches on many of these points can be found here:

https://github.com/borisyankov/DefinitelyTyped/issues/427

For early adopters of TypeScript, managing d.ts files is certainly a major pain point. Out of date d.ts files and/or lack of d.ts files for anything other than the most recent version of JS library I feel seriously undermine what TypeScript has to offer. In large-scale projects sometimes it feels like what you gain from the TypeScript language features are lost by having to manage poorly maintained or built d.ts files.
Oct 7, 2013 at 7:25 PM
Please see a proposed solution here: https://typescript.codeplex.com/discussions/461449