[Tracking Issue] Typing and proper usage of modern TypeScript features

[Jartreg]

The project technically uses TypeScript, but most things aren't strongly typed yet. In addition to that, there are many parts that look pretty weird when considering modern and idiomatic TypeScript conventions. This is why I would like to help with and advocate for proper strong typing and usage of modern TypeScript features.

This issue is intended to track the progress (if it is approved).

To get the project into the desired state, following steps would be necessary in the long term:

1. Adding strong types to existing interfaces
   • Types like any should only be used where it is explicitly necessary.
   • No implicit any in function declarations
   • The end goal would be to enable TypeScript's strict mode across the project.
2. Converting existing code and interfaces to idiomatic typescript
   • Proper use of ES classes
   • Replacing the old JS module pattern or static-only classes with ES modules (e.g. in ide.ts and lang/index.ts)
   • Going further (optional?): using inversion of control and readonly more
     For example the interpreter services could be interfaces with different implementations instead of reassigning certain methods in tests or docs. The interpreter would be passed the implementation once at construction time.

Benefits

1. Strong typing detects many errors at compile time instead of when it's too late
2. Most editors can give very high quality suggestions, improving maintainability (idk what editors most contributors use and how easy it is to set up a TypeScript lang server with them)
3. Modern ES syntax is less verbose that older patterns, making it easer to read
4. ES modules offer the desired isolation and can be split up with little effort when necessary
5. (Regarding IOC and readonly):
   • assigning a non-null value at construction time eliminates the otherwise necessary null-checks and non-null-assertions (!)
   • readonly avoids unexpected writes to properties when something is not expected to change

Drawbacks

1. TypeScript was quickly suggested and the initial "conversion" didn't add types for most things and used any extensively. I don't know how comfortable most contributors are with TypeScript and whether they really want to use it that extensively. In addition, I am biased in favour of it since I use an editor that doesn't need any setup for proper TypeScript support with suggestions and everything.

2. Interop
   The conversion of some internals in step 2 will add further differences to what the tools on the E-learning platform expect. Since these tools heavily use the parser's and interpreter's internals and are strictly speaking not public (e.g. as a user I can only know about isRecursive, hasStructure and so on), more effort in keeping them compatible would be needed.

   So far I see two ways to approach this:

   1. Add tests to verify their compatibility to this repository and add more emulation to the interop export
   2. Move them to this repository entirely to keep them up to date directly

I'd expect this to take quite some time and I wouldn't want to rush this (that's why I created this issue). What are your thoughts on this?

[TGlas]

I totally support the proposal, although I don't feel qualified to judge the consequences :)

The transition to TypeScript made sense to me, and what you propose now is mostly to complete the job. Transitioning to modern JS (ES6) is maybe an independent task, but it makes sense to do that in the same pass. I am not an experienced TypeScript developer, but I am eager to learn more about TypeScript and "idiomatic" ES6 in the process.

Concerning interoperability with the E-Learning tool, what I need is the ability to monitor the behavior and to analyze the structure of TScript code. Defining a stable interface for that task would be a valuable step forward. One option is to define how unit tests are specified and to add the ability to run them to the project, including error reporting and a grading mechanism. The alternative is to return a list of events (as it is done now), plus what is done by isRecursive and hasStructure, and to leave error reporting and grading to the caller. At least for now, both functions make lots of assumptions about internals. That's probably unavoidable to some extent, but hasStructure would anyway profit from a rewrite. It is unnecessarily hard to use and not well documented. Also, the corresponding tests are invoked by running arbitrary JS code with eval. That offers great flexibility, which is not really needed in retrospect.

There are currently two ways in which the interop version is used: on the client side, to test code directly in the browser, and similarly on the server side using node.js. In the browser, the solution is transparent to you. It is already included in the repo, see the (still deactivated) tutorial. On the server side, the same types of checks are run. This currently works by composing a big JS file containing the interop code, the TScript codes to run (as an array of string constants), and additional control code (heavily based on setTimeout loops, similar to run_multiple in the browser). It runs a series of tests with a single node.js invocation, and prints the JSON-encoded results to standard output. The node.js invocation comes from a C++ program, but that should be of no concern. The code grew over time. The current state is quite messy, but it works well. In the long run, it needs a rework anyway.

[TGlas]

I made some progress in this direction. A while ago, I had introduced functionality for evaluating code based on unit tests. It is required for the (still missing) tutorial. I have now updated and extended that part a bit. The functions provided by the evaluation module are now my only interface to the E-learning tool, both client and server side. Hence, the inter-operability needs of the project should now be much more clear.