Terra-core: Add Type Declaration Files for Terra Components

[juliacalandro]

Issue Description

The support for TypeScript, and type checking in general, is becoming increasingly widespread across the JavaScript and ReactJS community, as it makes JS code way more predictable and less bug-prone. Currently, Terra components are not compatible with any consumers that wish to use TypeScript or static type checking. My team has begun implementing type checking in our code base because we recognize the benefits and enhancements it provides us (advanced autocomplete, in-line documentation, go to definition, auto import). However, our main roadblock has been the fact that Terra components do not have type declarations, so the TypeScript compiler cannot accurately assess the components.

Therefore, we propose that Terra add Type Declaration Files for all components in terra-core, terra-clinical, and terra-framework. Since the size of these libraries isn't too large, we don't foresee a major time commitment being required for this change.

For more information about type declaration files, please reference the following links:
https://blog.mariusschulz.com/2014/05/19/using-typescripts-type-definition-files-to-get-tooling-support-for-plain-javascript
https://definitelytyped.org/guides/creating.html

Issue Type

• [x] New Feature
• [x] Enhancement
• [ ] Bug
• [ ] Other

Expected Behavior

Each Terra component has a corresponding type declaration which consumers can access and use within their type-checked projects.

[bjankord]

We've discussed this topic amongst the team and have found that type checking isn’t a problem that we feel needs to be solved for beyond what we're doing with react prop-types.

While there are benefits to adding TypeScript to Terra, there are also trade-offs that come with it. Here are a few concerns we have with TypeScript: potential lock-in as JavaScript evolves, worry about building up a large codebase using TypeScript, only to have the ECMAScript spec introduce conflicting keywords and type features, limiting available tools, increased build tool complexity / reduced build tool compatibility.

By using TypeScript, it limits the tools available to use. Instead of using ESLint, which has grown to become the de facto JavaScript linter, we'd have to use TSLint, which doesn't have the type of backing behind it compared to ESLint.

We've also found compatibility issues between TypeScript and Lerna, the tool we use to manage the monorepo.

An exerpt from https://medium.jonasbandi.net/here-is-why-you-might-not-want-to-use-typescript-50ab0d225bdd expands on the concern of lock-in with TypeScript.

When you start using TypeScript features (types, generics, enums, access modifiers …), your code does not run directly in a JavaScript runtime any more.
Your project becomes dependent on TypeScript. For a big code base written in TypeScript it would be a lot of work to get back to plain JavaScript.

The problem might arise in the long term. The current strength of TypeScript is that it is so closely aligned to JavaScript. This enables easy integration with the huge JavaScript ecosystem. Currently you can use TypeScript with almost every JavaScript library and framework. The TypeScript team clearly stated that this is also the goal for the future. This means new JavaScript features are also compatible with TypeScript.

However in a far future TypeScript might decide to deviate further away from JavaScript. This might impact the ease of integration with the JavaScript ecosystem a lot. Then TypeScript would just become another language that compiles to JavaScript, there are already a lot of those …

Another danger is that certain TypeScript features might clash with future JavaScript features and TypeScript has to change. This happened before with modules (I think TypeScript handled it gracefully, but there is still some friction in TypeScript aroundnamespace and module).

The next clash that is on the horizon is JavaScript introducing private fields.

Based on this, we do not have plans to add TypeScript to Terra.

While our team is not interested in adding TypeScript to Terra, you could add types for Terra components to your project. Here are a few resources for how that could be done:

• https://www.detroitlabs.com/blog/2018/02/28/adding-custom-type-definitions-to-a-third-party-library/
• https://medium.com/@chris_72272/migrating-to-typescript-write-a-declaration-file-for-a-third-party-npm-module-b1f75808ed2

[juliacalandro]

Actually, the goal was never to get Terra to convert their code base to TypeScript. My team isn’t actually moving to TypeScript as well. The goal was to add type declarations via documentation, so that the code can still be type-checked without being converted to TypeScript.

The reason why we didn’t just add the type declarations ourselves is because it would be very difficult for us to keep up with every new Terra release and check through the components to see if any props have been added, removed, or changed. Other open source projects have a larger consumer community of TypeScript developers who consistently work together to keep the typings up to date, but I’m not sure this is the case with Terra currently. We believe it would be easier for the Terra team in charge of the release to quickly update the type declarations because they know exactly which props of which components will be changing as part of the release. With that being said, we could add the initial typings, and then the Terra team could assist in keeping them up-to-date.

I also wanted to address a few of the arguments that were brought up as negatives for TypeScript.

TypeScript has consistently added full support for new EcmaScript features by phase 3 of their development/release cycle. I believe Terra wouldn’t use the new features until phase 4. Also, the TypeScript team goes to the regular TC39 meetings about upcoming EcmaScript features, so they are major stakeholders and know the exact features that will be added in the future. TypeScript now has major influence in the JavaScript community. It is actually interesting that a feature was proposed to EcmaScript and got turned down in the preceding TC39 meeting because it would clash with TypeScript. With that being said, the room for conflicts is very small due to the technical architecture of TypeScript. TypeScript is only the “declaration” while the plain JavaScript (the “implementation”) remains exactly the same.

The TypeScript team has stated that the entire premise of TypeScript and it’s purpose will always be to be a thin layer of static typing on top of JavaScript. The goal is to always be Javascript, but with types. If they diverge from that, it would be a completely different language than what it is right now which wouldn’t make sense.

The ESLint team created typescript-eslint-parser so it is not required to use TSLint at all. ESLint doesn’t work on JSX files anyways, so we have to use babel-eslint for JSX, and babel 7 has full support for TypeScript.

There are many projects and companies that use Lerna and TypeScript together. I’m not sure what compatibility issues were found.

These articles are good to read:
https://basarat.gitbooks.io/typescript/content/docs/why-typescript.html
https://eng.lyft.com/typescript-at-lyft-64f0702346ea
https://redditblog.com/2017/06/30/why-we-chose-typescript/
https://slack.engineering/typescript-at-slack-a81307fa288d

[mjhenkes]

To me types vs no types comes down to personal opinion and what you're used to. I personally don't see a lot of value in adding type checking to dynamic languages, but I know that others do. The tipping point with this issue is that it would increase maintenance work and complexity in the terra library and thats not something we're willing to commit to.