"Typings vs TSD"

[blakeembrey]

This was from an email. I asked to copy the content here to respond for visibility, the author opted to remain anonymous.

I'm fumbling through some rough edges with Typescript, Angular 2 beta, Webpack, etc. and found your starter template. (thanks for putting it out there!) Was confused why tsd install was not creating the typings folder that the code was expecting, until I realized your project is using "typings" npm package instead of "tsd" npm package, and that you are a contributor to "typings". After spending several days dealing with version dependencies of various packages I'm wondering why was "typings" created? I can understand pulling typings from github or another url, but really shouldn't that have been added to "tsd"? Isn't that the point of an open source project is that you can improve upon it if it doesn't meet your needs? Having another option makes things harder down the line in many respects. I also like the fact that tsd uses a single github repo DefinitelyTyped in the same way node package management uses npmjs. That centralizes statistic collection and makes everything simpler. I don't understand the benefit of opening it to any url. If there is a package you want out there, why not upload it to DefinitelyTyped? Or contribute changes to tsd to get it to work the way you desire? While I recognize the benefits, I think that is the down side of the wild west of open source forking. Just my 2c. Will dismount my high horse now. :)

[blakeembrey]

I'm wondering why was "typings" created?

I'm actually a contributor to both TSD and Typings, and the original idea of Typings come from DefinitelyTyped/tsd#150. That issue, "TSD Future", become this repo. There's a number of reasons Typings was created, but I'll focus on the points as to why this didn't end up as "TSD Future".

1. I focused on using external modules as first-class. Why external modules? It's what the TypeScript compiler generates already, since 1.6 it's also what the TypeScript compiler can consume (using node module resolution) and external modules have clearly defined boundaries (no parts are ambient). I spent weeks trying to find a transparent way to rewrite the ambient declarations in DefinitelyTyped, but ended up with it needing manual refactoring.
2. I wanted to focus on using sources from anywhere. If you've ever typed something missing in DefinitelyTyped, you'll have run into this. You typed it, but to use it with TSD you need to wait forever for it to merge and whatnot. This is because the registry for TSD is the DefinitelyTyped repo. It's confusing and conflicting, as the namespaces are almost meaningless - they could be on NPM, Bower or just arbitrary. There's also little consistency on exposing the versions, etc. Just look at the registry entries I have parsed, and I know about 1000 entries in DefinitelyTyped don't have the version they were typed against. This is solved using https://github.com/typings/registry and allowing installations from anywhere (in case you can't wait until it merges into the registry, which usually you can't).
3. I needed something that worked with actual package managers. Have you ever tried to publish a package that uses TSD typings? Well, don't, you actually can't. This is because your typings will conflict with your users typings and so on. Just see all the issues in Angular around this for proof (Cannot use Mocha to write angular2 tests angular/angular#5395, typings from angular2 conflict with project typings angular/angular#5807, external typings are not referenced anymore angular/angular#5565, Type definition conflict with jQuery TSD angular/angular#5459)
4. I needed typings management to be scalable. Having hundreds of people pinged when one typing gets changed because you're using a giant repo is no fun, I would just unsubscribe personally. But when everyone unsubscribes no one gets their PRs merged. Having decentralization of the typings themselves means that the maintainer can actually do their job, and just maintain their own typings. Want to add other collaborators, guess what, it's built into GitHub already 😄

but really shouldn't that have been added to "tsd"?

See the reasons above. I didn't end up doing this in TSD since it's a complete rewrite and breaks DefinitelyTyped. Breaking an ecosystem people have relied on for two years is no fun, even if it is flawed. So I created this organization and hope to add more people to contribute to it. In the meantime though, everyone can continue contributing in their own way by adding their own typings to the registry. This is more powerful because I can actually build better intelligence for users here.

Isn't that the point of an open source project is that you can improve upon it if it doesn't meet your needs?

See the first answer, I did try. I tried really hard. But the whole thing is just not compatible.

Having another option makes things harder down the line in many respects.

How? If you want the old behavior, I've actually already enabled it. Just use typings init --upgrade to switch to typings. I'll be improving compatibility over time to make upgrading even easier. Recently I released an API (semi-public, but in use already) that is even parsing all of DefinitelyTyped already. See https://api.typings.org/search.

I also like the fact that tsd uses a single github repo DefinitelyTyped in the same way node package management uses npmjs.

This isn't an equal comparison really. The comparison here is if everyone did development in a single repo, but we published thousands of packages from that same repo. It doesn't really scale. It isn't really enjoyable for anyone. Even in a company, you don't just put every product you build in a single repo. Once you have a hundred engineers, every needs to be able to work independently without squashing each others toes.

That centralizes statistic collection and makes everything simpler

Not sure what it makes simpler. What is "everything"? Also, statistics collection? The current project queries GitHub, the only people with those statistics is Google. Using the registry API I mentioned above solves this anyway, since it can include statistics.

I don't understand the benefit of opening it to any url. If there is a package you want out there, why not upload it to DefinitelyTyped? Or contribute changes to tsd to get it to work the way you desire?

Covered in previous responses.

I think that is the down side of the wild west of open source forking

This isn't really a fork. It's a complete rewrite. It's a different way to think about typings. It's decoupling. Sure, it could go in TSD. But when I break everyones workflows and require a rewrite for everyone involved because things are so tightly coupled, it's not fun. It isn't possible to do what I did here in DefinitelyTyped, because of the structure which they have to stick to because a bunch of tooling already relies on it. How many good things do you hear about relying on folder structure? You can never refactor properly unless you break peoples code.

In the end, it's much more powerful and open for anyone to contribute and use. People can write internal typings and use them without having to expose the information, which is a pretty often request too. Even Angular maintains their own fork of DefinitelyTyped because of this limitation in TSD.

Anyway, thanks for the questions! You aren't the only one with them and it's hard to see why this is worthwhile sometimes. There needs to be clear definitions between ambient and external to me, which is the most important thing. For instance, Mocha is technically three typings - the module (external) and two environments (ambient - TDD and BDD). Having them all lumped together won't work forever.

I'm going to leave this issue open until I build a docs folder for things like this 😄

[Pickra]

👍

[glen-84]

It was the correct decision IMHO. Keep up the great work. 👍

[dsebastien]

👍

[samvloeberghs]

👍

[matijagrcic]

@blakeembrey Thanks for explaining why typings was created. Keep up the great work.

[unional]

Maybe it is a good idea to put this on the Wiki page so you have one less "issue" to keep track. :P

[ackimwilliams]

👍 Thanks for updating the community on the benefits of typings and your reasoning. Keep up the good work.

[SonofNun15]

👍

[blakeembrey]

Closing for housecleaning. Feel free to continue discussions 😄

[nicojs]

I mostly agree, except for this point:

I didn't end up doing this in TSD since it's a complete rewrite and breaks DefinitelyTyped. Breaking an ecosystem people have relied on for two years is no fun, even if it is flawed. So I created this organization and hope to add more people to contribute to it.

Breaking api's is where a major versions are for. Just look at angular 2 for example. I understand it would be frustrating for companies, but what is the difference with the current approach? Seeing a deprecated declaration in the tsd repo means that big companies will also feel the need to move to typings, which is effectively the same. Also typings init --upgrade could also be part of the major version of tsd. It is arguably even a bigger change now, because we all need to update our internal documentation (find and replace tsd with typings) and reeducate people, etc.

Anyhow, I don't really care one way or the other ;). Just thought i point this out.

What i do find difficult to grasp is why i have 2 folders in my typings folder, browser and main. I don't really see any difference between the to either (for example: $ typings install domready gives me the exact same index.d.ts file in both folders). I guess one should be used for web applications and the other one for nodejs applications? And do i check them into source control? What is the idea here? I don't see that explained anywhere, or am i missing something?

[blakeembrey]

@nicojs Your welcome to have you're own opinion, but I don't think people should release a module with the same name when you fundamentally change the entire concept. Your Angular 2 example is particularly useful for this comparison as it's a big change and probably should be been released as a new library - people will be landing on completely irrelevant books and docs and help pages for years to come. However, compare that to Express.js vs Koa - it's fundamentally a different approach and making it "express.js 5.x" would not make sense as it's a rethinking and a different model.

Either way, you would need to have updated your documentation. It wasn't compatible anyway. Also, re-education is exactly the same situation, except TSD would come with all the existing baggage (baggage that I've tried my best to support for people who are coming from TSD). Also, TSD was not deprecated until months after I had released this - but no one was maintaining it and I didn't want to be maintaining and answering questions for both repositories when a better solution existed.

For the answer on why there's two folders, please search for existing issues and it's in the FAQ. Please don't check in generated files into source control, that's just a general rule. However, as with everything, it's each to their own.

[nicojs]

@blakeembrey Thanks for the response. I still didn't change my mind, but like i said, i don't really care one way or the other.

I found the FAQ, but i've got to say, it didn't really clarify the why for me. For the browser.d.ts vs main.d.ts. If you want, i can create an issue for it and explain exactly what is unclear?

[unional]

@nicojs , regarding browser.d.ts, you can also take a look in this in-depth discussion: #151

I agree that the faq does not address the why, but it is complicated and input are always welcome. 🌹