By building the library from the ground up with types, you make clear what are the constraints and preconditions of your API.
Often in JS libraries, the types are vaguely defined as an afterthought when writing docs. Each function is described as “we expect the argument to be X” but this is not always thoroughly thought, and sometimes leaves holes. Either the function can accept more types than what was documented or the function has invisible constraints that were not communicated in the docs, which leads to runtime errors.
This happens at least in Visual Studio Code.
Types are there whether you like it or not. APIs never accept “whatever” and output “whatever”. There are always preconditions and postconditions. Good library APIs have good contracts.
Usually, a method accepts either a string or a number or a function or an object, etc.
Even if the method accepts objects with varied structure, you always have some assumptions of what is a valid object or not. For instance, maybe all the properties are optional and some of them are
host, but these are usually a limited amount of predefined properties, and e.g. the typo
paload would be an invalid property.
The types are there. Instead of leaving them implicit, you can just make them explicit. Interfaces are a good way of defining the structure of valid objects.
But some people may choose to build their project in TypeScript, and for those, you will be making their life much easier if your types are built from bottom up, instead of stamped on top as an afterthought
.d.ts type definition file. By building the library from ground up in TypeScript, it is more likely your
.d.ts files will be reliably reflecting the actual type constraints.
Why not build libraries in Flow? Flow is good and very similar to TypeScript. There is nothing wrong with Flow, and in some aspects it has advantages over TypeScript with its nullable vs non-nullable type annotations. At the time of writing, TypeScript does not support that feature.
I would argue that while nullable and non-nullable annotations are great, both Flow and TypeScript provide compile-time type checking for most of your type constraints, and TypeScript is slightly ahead since it had the benefit of a head start. I hope TypeScript one day gets nullable and non-nullable annotations. In the meanwhile, I like to compare TypeScript vs Flow as Git vs Mercurial. Both of the competing technologies are very similar, they may have their minor pros and cons, but one of them is considerably ahead in adoption and quickly gaining the status of a solid foundation on which to build software.
And some type definitions are better than none. It may be quite feasible to build conversions from
.d.ts files today will help us in the future to migrate towards it.
If you liked this article, consider sharing (tweeting) it to your followers.
Copyright (C) 2016 Andre 'Staltz' Medeiros, licensed under Creative Commons BY-NC 4.0, translations to other languages allowed. You can make sure that the author wrote this post by copy-pasting this signature into this Keybase page.