Add "Typings" file to NPM package for Typescript consumers

[thw0rted]

I've been working on a Cesium-based project for a few months now, and picked Visual Studio Code as my primary editor. I was a little irritated that other libraries I rely on (like Moment and jQuery) have good feedback from Intellisense, while Cesium doesn't give me anything (out of the box, at least). I learned that this is because the more popular libraries have a "Typings" file (.d.ts) either available from an external source, or bundled into the Node module directly.

I found this repo and placed the index.d.ts in my node_modules/cesium/ and like magic, VSCode knew the types of all the Cesium classes and functions -- except that listing was last updated 4 months ago with version 1.26, so it was missing stuff that's changed in the last half-dozen or so releases. I've added some things to it myself, though I wouldn't say it's definitely complete. I can post my modified version if anybody would like that.

I recognize that this would be an ongoing requirement, either to maintain manually or to generate as part of your build workflow, but I think it would really help out both those that try to use Cesium from actual Typescript, and those that work with vanilla-JS Cesium from VSCode.

[ggetz]

Hi, thanks @thw0rted! There's been previous discussion about starting to use Typescript (see #4434) and it's included on our BIM Roadmap if you'd like to contribute to discussions there.

[hpinkos]

We've been talking about updating to es6 modules sometime soon, so we may be able to do this as part of that effort.

[mramato]

ES6 is orthogonal to this.

The best way to implement this would be to automatically generate it from the jsDoc comments, which is what some of our users have tried doing. (I believe jsDoc already outputs an interim json document that makes this straightforward). Hopefully there is a standard tool available that we can use to validate the output so we can automatically detect when it's broken as well. I imagine there are bugs in the jsDoc that would have to be cleaned up in the process as well.

It's doubtful that the core team will be able to do this anytime soon, but if someone would like to implement a gulp task that generates the definition file, we would be happy to take the contribution, it just needs to be auto-generated and cleanly written so that it's minimal work for us to maintain going forward.

[thw0rted]

I read #4434, and while moving to TS would be neat and all, I'm talking about "just" adding typings sooner rather than later. As Matt points out I think this is reasonably straightforward if the JSDoc is already correct (and of course, if the JSDoc isn't correct, it should be updated).

In the past few days working with it, the biggest hangup has been dealing with Property types. I don't know a lot of Typescript so if there's a way to say that you can assign any other type (or specific other types, declared as a generic like Property<boolean>) and implicitly convert, I haven't found it. I updated a lot of type members that are listed as just Property in the docs to be Property | Color (or boolean or number or whatever), just so that assignments work. I'll look into the toolchain to generate the typings file from a gulp task, but we need to figure out the Property thing before the output will really be useful.

[thw0rted]

Oh! And I forgot, while ES6 is kinda-sorta orthogonal, I believe that importing an ES6 module in VSCode will apply Typescript-style static checking to the JSDoc (if intact) which would mean you wouldn't strictly need a typings file to get Intellisense working. (You might still need the file to actually include Cesium in a Typescript project without copping out and calling it any?)

[thw0rted]

I'm trying to rectify how Cesium handles Property with how Typescript wants this to work.

For example, in a simple Billboard Sandcastle, I can set viewer.entities.billboard.show = false and it appears to be setting a property of the billboard. Under the hood, it looks like the setter is creating a ConstantProperty and saving that to a private member. This is a common pattern across the sample code.

Typescript has some strong opinions about this. From that issue:

I truly object to the idea that this code foo.bar = "hello"; console.log(foo.bar); should ever print anything than "hello" in a language that attempts to have sane semantics.
Properties should have behavior that is indistinguishable from fields to external observers.

This is on an issue talking about why Typescript won't let type types of a getter/setter pair differ from each other. So there's currently no way to declare typings such that billboard.show = true; works and so does if(defined(billboard.show) && billboard.show.getValue()){ ... }. You can declare show as being of type Property | boolean (which is exactly what I did for the constructor options) but that means that you have to add a type guard any time you get the property, even though you know it will always be a Property and not a raw boolean.

[mramato]

While I don't have a good answer for you, what Cesium is inspired by another Microsoft language, C# and is normally referred to as implicit construction. You can read more about it here: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/implicit It's not that the setter/getter are different types, it's that the Property type is automatically instantiated during the assignment. Conceptually, you are always setting a Property type, it's just created on the fly.

I don't know enough about TypeScript to know if it has any sort of implicit construction, but if there is any such concept, I think that could be used here. Ideally, in the TS definition, it should always say Property{bool} (or whatever the generic notation is) is the type for the getter/setter, but it would know that Property can be implicitly cast from bool.

Of course this is me talking in the abstract and unlikely to have a good TS solution, but I just wanted to provide some context as to the idea behind the properties.

I also wonder if we can lie to TS for the sake of a good definition file, even if the actual implementation is slightly different.

[thw0rted]

I did a little research about implicit cast / implicit construction but didn't have time to really get into it. I'm familiar with the idea, and the good news is that Anders Hejlsberg worked on both languages so there's probably support for getting the feature in there if it's not already. I believe some primitive types can already be implicitly assigned / cast to one another, so hopefully there's some way to shoehorn in implicit construction too.

Maybe I should take this to the TypeScript tracker for more details...

[thw0rted]

If anybody is tracking, I went ahead and hand-jammed some 1.37.0 updates to the Typings file I found earlier: https://gist.github.com/thw0rted/c0c73335c9968d5e7b6dd18a43ef6c42

I'm sure it's still missing some information or wrong in places, and I don't have automated tooling in place to generate this, which is what's really needed. Still no workaround as far as I know for the issue I raised back in August -- Typescript still really doesn't want you to use getter/setter pairs the way Cesium does, so you might have to do use type guards or casts in your consuming code that wouldn't otherwise be necessary.

[emackey]

I stumbled across another thing to consider here: TypeScript without Transpiling.

TypeScript 2.3, which arrived in April, introduced support for analyzing conventional JavaScript code that has type annotations in comments. You can use a JSDoc-inspired syntax to describe function signatures and add type information. TypeScript tools read the type annotations from the comments and use them in much the same way that they use TypeScript’s own type system.

JavaScript with type annotations in comments is less succinct than writing actual TypeScript code, but it works everywhere, it eliminates the need for transpiling, and it makes the TypeScript tooling totally optional. It doesn’t cover all the same ground as the TypeScript language yet, but it is comprehensive enough to be useful.

[beginor]

@thw0rted I have move your gist to a public repo https://github.com/beginor/cesium-typings , this make it easy for others to contribute.

Any star or fork is welcome.