Cesium: Let us slowly move to Typescript. (instructions inside)

[ghost]

I set up Typescript pretty easily with Cesium (with minimal friction).

1. Install Typescript:
   npm install --save-dev typescript
2. Create a file in the root directory tsconfig.json:

{ "compilerOptions": { "target": "es3", "module": "amd" }, "include": [ "./Source/**/*.ts" ] }

1. Rename all js files in the pattern below (except the ones with "!") to .ts (taken from gulpfile.js):

['Source/**/*.js', '!Source/*.js', '!Source/Workers/**', '!Source/ThirdParty/Workers/**', 'Source/Workers/createTaskProcessorWorker.js'];

I just went in the directories (not the "!" ones) and ran the recursive command:

find . -name "*.js" -exec rename 's/\.js$/.ts/' '{}' \;

1. Use the Typescript watcher to automatically compile Typescript to Javascript upon changes:

tsc -w -p .

1. The resulting Javascript files will be placed next to the ts files. This will let us keep our current build process and reap the benefits of Typescript with minimal effort. We can just use a .gitignore for the js files. gulp-typescript does exist (see link at bottom).

Remember that Typescript is a superset of Javascript. Therefore, all of our current code works completely fine. Now, we can incrementally migrate. With type-checking, compiler options like strictNullChecks, noImplicitAny, noImplicitReturns, and much more (see link below), a proper module system with import/export, we can create new features faster and find dormant bugs (with type checking). Also, less tests! We don't have many contributors... so Typescript would definitely help. And you can finally use a proper IDE with autocomplete and refactoring tools.

We can complicate the build process with gulp-typescript and more, but I want us to start with the bare minimum first so we don't scare anyone away. Minimal friction is the keyword here.

• Typescript with Gulp
• Migrating from JavaScript
• Incrementally Migrating JavaScript AMD Project to TypeScript
• Compiler Options

[pjcozzi]

@thinkpadder1 thanks for the notes on Typescript. In the future, we would prefer that you start a discussion on the forum for something like this. Given its incredible impact, it will require significant discussion. For now, we'll have to table the discussion as we are heads down on 3D Tiles, but I have labeled this 2.0 so it can be considered when we make bigger module changes.

In the meantime, you might want to research how this would affect Node.js users of Cesium and how the transpiler would impact development; the core dev team will insist on a smooth dev experience with virtually no overhead.

[mramato]

Thanks for the list of resources and getting started details @thinkpadder1. I would love to move to something like TypeScript and I know @kring is a bing proponent as well. It will be a non-trivial effort and I agree with @pjcozzi isn't not something that can happen until the 3D Tiles work is done (given the amount of new code that that branch will introduce and the amount of time to get the team used to working in TypeScript).

It's definitely something I would start prototyping at a hackathon or when I suddenly have free time if no one beats me to it. My main concerns are testing, coverage, performance, and backwards compatibility with existing Cesium applications. I also wouldn't mind surveying the JS landscape and see what possible benefits TypeScript would provide over other approaches, like Babble and flow. I'm fairly confident that TypeScript will win out here, but we need to do our due diligence.

[kring]

I spent a bunch of time looking at using TypeScript for TerriaJS. The main problem with it was the ecosystem. You can't use jsdoc or eslint, for example. Similar tools for TypeScript are far less mature. In many cases, tools that initially looked promising were expecting older versions of TypeScript and hadn't been updated in many months. I even tried ugly hacks like having the TS compiler generate JavaScript with comments and then running that through jsdoc, but I couldn't get it to work reliably.

This was probably 8 months ago now, so maybe things have improved.

Unfortunately, IMO, the ecosystem matters just as much if not more than the language. In the end we ended up going with ES2015 and Babel. We haven't really tried Flow yet, but it looks pretty good.

[mramato]

Thanks @kring those were exactly the types of problems I was worried about. Even if things have improved, it shows that this is actually a major change for our code and definitely will require lots of thought and planning.

As an aside, since you went with 2015 and Babel, are you using modules? How does testing and coverage get handled with transcompilation?

[ghost]

@kring For linting, see TSLint.
If you really need ESLint, the ESLint team is working on it (experimental): typescript-eslint-parser.

Typescript supports JSDoc style comments and works great in Visual Studio Code. Even if you don't use Typescript, it's a great editor with the Salsa service.

There are even extensions that will generate most of the JSDoc for you: Document This

Here is a list of all currently supported JSDoc annotations (which is being actively worked on).

Lastly, someone is working on a JSDoc to Typescript Definitions plugin and he is targeting Cesium + OpenLayers: jsdoc-typescript-plugin. It could be the middle ground between sticking with what Cesium has and fully committing to Typescript (at the bare minimum, it would help people using Cesium).

[kring]

@thinkpadder1 yeah I had previously discovered TSLint, as well as typescript-eslint-parser. It looks like both have made some progress since I've looked, but still aren't nearly mature as ESLint with Babel.

re: doc, those things are all nice, but they don't help us generate the documentation on cesiumjs.org: http://cesiumjs.org/refdoc.html

[ghost]

@kring Have you guys looked at TypeDoc?

Cloudflare uses it: Generating Documentation for TypeScript Projects

The post shows how to use it and compares it against JSDoc.

[custompro12]

Any update on this?

[mramato]

As of Cesium 1.70.0, we are shipping official TypeScript definitions. If you want to read all of the gory details, and potential future plans for TypeScript and CesiumJS, check out this blog post: https://cesium.com/blog/2020/06/01/cesiumjs-tsd/

Sometime over the next week or so, I'll be consolidating any TypeScript issues into a new master issue for plans going forward.

Thanks!

[bampakoa]

@mramato I think that you meant we are shipping :smile:

[mramato]

Whoops, thanks. It was supposed to say "now shipping" fixed :smile: