Opentelemetry-js: Typescript vs Pure Javascript

[mayurkale22]

Originates from https://github.com/open-telemetry/opentelemetry-node/issues/3#issuecomment-495348355

[vmarchaud]

+1 for Typescript mainly for the experience as a developer of the future implementation, completion and static check are a must have for me.

If the con is compatibility with older versions, i believe having specific bundle (with shim for promise for exemple) for older versions is the easiest way.

[rochdev]

+1 for JavaScript with corresponding TypeScript definition files. This would provide all the benefits of both JavaScript and TypeScript, without all the disadvantages of going completely with TypeScript. Static checks are supported with this model for example.

There are many downsides to using TypeScript as described in https://github.com/open-telemetry/opentelemetry-node/issues/3#issuecomment-495348355.

If we decide to go with TypeScript, we need to have a discussion about how to make sure it doesn't impact the developer experience (slow builds preventing TDD, etc) and how to properly handle different code paths per version of Node/ECMAScript.

One alternative potentially would be to remove any transpilation feature and shims and handle these concerns outside of TypeScript. Then TypeScript would be used almost exclusively for type safety, which would provide an experience similar to my above proposition.

[c24t]

FWIW we're considering using type hints in the python API package but not the SDK. It's an apples-to-oranges comparison since type hints are a language feature and don't e.g. require transpiling code, but gives us the same benefit of a well-defined API and optional static checks for the implementation.

[rochdev]

One thing also is that it's easy to move from JavaScript to TypeScript if necessary (especially if the definition files are already done) but the opposite is not true, especially with many transpilation features enabled, so it would be safer to start with JavaScript.

[mayurkale22]

+1 for Typescript. With TypeScript,

• I can trust my code at runtime (Strongly-typed or supports static typing).
• Better code structuring and object-oriented programming techniques.
• Code easier to understand (and refactor).
• Will help everyone collaborate easily, can increase productivity.
• Better IDE support
• My development experience is fantastic.

[rochdev]

I can trust my code at runtime (Strongly-typed or supports static typing).

You cannot for a library that is used by a majority of JavaScript users. Tests are still needed for most types (false sense of safety).

Better code structuring and object-oriented programming techniques.

A lot of JavaScript patterns and best practices deviate from OOP and tend to be more on the functional side. They are usually very difficult to type properly.

Code easier to understand (and refactor).

I would argue that it makes the code a hell of a lot verbose, but I agree that the intent is clearer and that IDEs can usually refactor pretty much anything.

Will help everyone collaborate easily, can increase productivity.

I've never seen a single project where productivity was actually increased by TypeScript unless they were not unit testing, or relying on types to guide junior developers. In fact, it tends to be the opposite.

Also, every TypeScript developer knows JavaScript but the opposite is not true, so JavaScript makes it easier to collaborate (arguable since we still need to have definition files).

Better IDE support

VSCode (and probably others) is able to use TypeScript definition files even for JavaScript).

My development experience is fantastic.

Mine isn't, but this is subjective, similar to any debate between programming languages in general. I don't like Java, but most of the world likes Java (statistically).

(Sorry if I'm very vocal in this thread, but I know I'll be playing devil's advocate here 😄)

[mayurkale22]

These are some interesting and valid points, let's continue this discussion in SIG meeting. @vmarchaud @rochdev @bg451 @hekike @danielkhan @justindsmith Can you please update availability here or gitter channel.

[jinmel]

+1 for Typescript

I agree with @rochdev there are many pure javascript hacks/flexibility however while this works great for small optimizable packages, I don't think its the same for large project like this one.

since we are holding many cross dependent packages in one repository I think it is helpful for developers to have common strong data type.

[draffensperger]

First @rochdev I appreciate your concerns on using TypeScript, and we should definitely consider both sides for key design decisions like this. I agree that for TS to work smoothly for us we will need the tooling to make incremental TDD and local dev easy. TypeScript 3.4 recently added a feature for Faster subsequent builds with the --incremental flag and I think we should use that to try to reduce the pain of compile type.

I will likely miss the SIG since I'm on vacation June 10-19, so I'd like to give my +1 for TypeScript here (I'm late to the convo because I forgot to turn on notifications for the repo).

My reasons for preferring TS:

• Types are enforced documentation: having the types specified inline with the code lets library users easily see exactly what they need to pass into a function and what is returned. Yes, types can be explicitly documented, but having them in the code and enforced by the compiler makes them a form of documentation that is enforced to be up to date.
• Types make refactoring safer: I agree that unit tests are also needed and we should strive for high test coverage (100% ?), but even with full test coverage, TS still makes refactoring easier because you can use the TS tooling for renames and the compiler errors will likely be clearer than test failure messages.
• Types help prevent errors and edge cases: for example, TS can verify that an implementing class has every method of an interface, or that a switch statement has cases for every possible value of an enum. These type checks act as a defense-in-depth mechanism alongside unit test to prevent runtime errors. Yes, unit tests are the first line of defense - but to continue the security analogy, just because you have an external firewall doesn't mean you shouldn't also encrypt traffic between your microservices.
• Use of TS enforces that .d.ts files stay updated: if we use vanilla JS, we would need to manually maintain a set of .d.ts files for the library so that TypeScript users of it can get the types. That means some of the burden of writing types would be needed even for JS, and it also means that if we use JS, we risk those type files going out of date or being incomplete because people forget to update them or they don't capture all the subtleties of the types.
• Types enable advanced Closure optimization for browser bundles: we talked in https://github.com/open-telemetry/opentelemetry-node/issues/3 and https://github.com/open-telemetry/opentelemetry-node/pull/2 about making the core parts of the library compatible with the browser. It would be great to be able to distribute minified JS bundles of the library in various configurations for easy use in a <script> tag. The Closure compiler can use type information to perform more aggressive optimizations, and if we use TypeScript, we can auto-generate those annotations using the Tsickle utility. This enables more optimized JS bundles to distribute (and more optimized code for anyone using the Closure compiler + Tsickle in their project). I have not yet measured how large the effect of type hinting is for optimization, but I hope to do so for opencensus-web at some point. But regarding use of Closure generally, the MS Office Online team saw Performance gains from switching to Closure Compiler with about a 15% reduction in bundle size and 8% improvement in page boot time - I'm not sure how much type hinting they used though.

Some additional considerations:

• Regarding OO vs. functional: types work great for functional style code too, e.g. if you map an array from one type to another, the return type of the map function determines the output of the mapped array. I think the TS/JS language lends itself naturally to functional style for many aspects and I think we should embrace those when it makes sense (e.g. don't just write a wrapper class for some helper functions because you do it that way in Java - just write and export the functions).
• Regarding TS as a reversible decision: if we start with TypeScript, we can actually revert to JavaScript by checking in the pretty-printed JS code produced by the TypeScript. The TS compiler supports a flag to preserve comments in generated code. While JS is valid TS code, trying to bolt types on after the fact is tricky and would likely involve various incompletely specified types over time.
• Allowing vanilla JS for vendor-specific code: I would be open to allowing vendors to write their exporters using plain JS if they prefer, and also to allow some instrumentation plugins to use vanilla JS if they prefer (e.g. if a specialized database vendor wants to write JS for their instrumentation plugin).

[rochdev]

It was agreed at today's meeting that TypeScript will be the language for this project. However, there are a few key things to keep in mind to make sure that we are able to provide the best developer experience and minimize issues between supported versions while using TypeScript. I will open an issue to discuss TypeScript guidelines to be added to the project once the initial skeleton is merged.

[mayurkale22]

@bogdandrutu and @SergeyKanzhelev any thoughts ?

[SergeyKanzhelev]

TS would be OK with us. It will give the best return on the bucks. And later we can cover whatever edge scenarios needed.

[mayurkale22]

Closing this, agreed to use TypeScript for the project.