v0.1

Post Mortem

Some lessons learnt from the Typescript project.

General Language Observations

In general, very good experience writing Typescript. Building class hierarchies, defining interfaces, abstract classes, etc. is very convenient. In particular, all necessary typing for HTML elements etc is already built into the language. This is certainly an advantage over other approaches like closure, where these types (and in particular the associated API functions) have to be explicitly defined in extern files.

Pros

• All necessary typing for HTML elements etc is already built into the language. This is a certainly an advantage over other approaches like closure, where these types (and in particular the associated API functions) have to be explicitly defined in extern files.
• Generics (e.g., in the Variable class are available.
• Types can be very fine grained (see example of JSON types), maybe sometimes too specific.
• Overloading works, although it could be a bit cleaner.
  • For simple overloading see the insert and remove method in the menu_store class.
  • For incremental overloading see post method in the postable interface and its refinement in the context_menu class.

Cons

• Enum structures are only definable on numbers. An example is in the definition of enum structures for events. E.g., key events can be defined via as typescript enum, whereas mouse events are defined as a sort of "pseudo-enum" structure via regular objects.
• String subtyping can be a bit awkward (see html class and attribute types), in particular when strings are generated.
• Some modern functionality is not yet integrated. In particular, promises are still missing.

All of these observations are for Typescript v1.8.10. At least the last point should change in 2.0, which is currently in beta.

Minimisation

Typescript's compiler tsc does not provide a minimisation option. I tried two minifiers:

UglifyJS

Minified code was 44KB. Code sample in samples/scripts

Closure

Minified code was 33KB, mainly because closure is better at compressing constructors and prototype assignments. Command used:

 java -jar ~/node_modules/closurecompiler/compiler/closure-compiler-v20160713.jar --js context_menu.js --create_source_map tt.map --js_output_file tt.min.js

However, it has drawbacks with respect to code maps. See next.

Code Maps

Code maps can be generated both with typescripts and via minifiers. For the commands and options generating code maps in the scripts directory see this script.

Direct Code Maps

Typescript can generate code maps directly which allow console debugging by working with the original Typescript source, rather than the transpiled JavaScript. This allows to set break points, inspect variable values, etc. See the example for a direct code map.

Minified Code Maps

Depending on the minifier code maps can be generated either for the Typescript or the transpiled JavaScript only.

• Uglify can take an existing code map and combine it with the minified code to allow direct debugging on Typescript sources. See the example file.

• Closure on the other hand can only generate code maps for the JavaScript it minifies, i.e., destroying the link to the original Typescript. (For the command see above.)

So one recommendation could be to use Uglify for development versions and Closure for general distribution.

Documentations

Code commenting follows JSDoc standards. This can be used for documentation extraction using a corresponding generator. The command steps generating the documentation below are collated in is script.

Typedoc

This is generated with typedoc generator.

For some reason it does not work on the actual github pages. E.g., go to the github.io version and then try to go to one of the module pages (e.g., for abstract_entry.

JSDoc

This is created with regular JSDoc generator from a typescript transpiled into ES2015 keeping comments, plus some tricks to get the "pseudo-enum" structures out, given in the tools directory. Unfortunately, JSDoc does not work out of the box on Typescript Interfaces and fails when constructors are implicit (i.e., not explicitly included in the JS class with JSDoc comments).

UML class diagrams

We have some tools to compile UML style class diagrams using graphviz/dot. Here is a script for that generates class diagrams in SVG.

• Simple Class Diagram containing interface and class relations only.
• Complete Class Diagram containing list of class methods.

Linting

The code base has been fully linted using tslint plus some homegrown helpers:

• tsling-jsdoc-rules Visitor for TSLint to check for existence of JSDoc comments in Typescript code.
• tslint-unix-formatter A Unix style formatter for tslint output.

Other remarks:

• Flow provides static type checking and can help turning untyped code base into a typed one.
  • It does not transpile or anything.
  • I did not get it to give useful output for Typescript files.
  • However, I managed to run some type checking on existing MathJax code.
  • Also interesting for comparison, see here and here.
• Typescript to closure compiler exists, but it currently only works with Typescript 1.7. Seems to still be an active project.
• Typescript plugin for JSDoc could do the job of my brittle code to rewrite JS files for JSDoc, but I could not get it to work properly. And it seems to be outdated/defunct.