TypeScript (Help Wanted)

[tschaub]

I'd like to see if we can publish TypeScript definitions for the 5.0 release. My understanding is that these can be published as @types/ol or in the ol package itself. I assume we'll need more than a single index.d.ts since we do not make everything exportable from a single module. I'm hoping we can automatically generate the TypeScript definitions from existing JSDoc annotations in the code. Perhaps this will be a migration path away from JSDoc annotations to authoring in TypeScript, but initially I think our goal should be to publish TypeScript definitions that are in sync with the code.

I'll be doing some more reading, but if anybody has experience and knowledge that they can spread, please let us know.

[marcjansen]

Ping @KaiVolland @atd-schubert @chrismayer

[tschaub]

@yairtawil - given your work on DefinitelyTyped/DefinitelyTyped#22894, I'm curious what you would suggest in terms of automating TypeScript definition files (dts-gen doesn't look that promising for ES modules).

[atd-schubert]

As long as you can also insert your TypeScript type definitions into your own module you should not apply them to DefinitelyTyped (DT). In addition there is already a definition on DT.

My recommendation is to insert a new definition based on the existing one with the help of the current definition author (@yairtawil). After that you can set the current type definition on DT as deprecated and maintain it in your module directly.

I can also help you a litte bit, if you wish.

[marcjansen]

Please help, @atd-schubert. Your feedback is much appreciated.

[chrismayer]

Wouldn't it make sense to have more members defined in the TypeScript types? In the Definition Files at https://github.com/DefinitelyTyped/DefinitelyTyped/ all classes are modelled like this

import * as ol from 'openlayers';

export default ol.layer.Vector;

Does it make sense to have the members like extent and visible defined there as well?

I just started with this TypeScript things, so sorry if I am wrong.

[atd-schubert]

Maybe another topic for our FOSSGIS Hacking-Event in Essen 😄

[beginor]

maybe it is time to switch to typescript 😄

[atd-schubert]

@chrismayer of course you can just make an index.d.ts file that exports other type definition files maintained by different people for every class, if it that what you meant with your comment. I would strongly recommend doing this on big projects like OL.

The biggest advantage on TypeScript you will have when you switch to TypeScript completely like @beginor asked in his comment. TypeScript will check your source-code against contradictions. As long as you just write a type definition file TypeScript is not able to proof your theoretical type definition against the actual. In my current job I convert a lot of libraries to TypeScript and always found wrong architectural implementations during the rewrite process! TypeScript can not find them by a simple type definition, you will find them after you fail in a specific enough situation.

There is also a strong argument against TypeScript. JavaScript is undisputed the programming language with the biggest community. Switching to TypeScript minimize you potential community, especially for pull requests. On the other hand you will increase your code quality and stability that also has an influence on your projects community.

Writing a type definition in parallel has also the problem that you have to keep your definition up-to-date! So maybe someone can make a pull request easier in JavaScript, but on every change someone else have to check if there is also a change in the type definition! You have to develop your library in two different languages and it is on your responsibility that your codes will not differ!

So in the end the maintainers should ask themselves this question first: "Do you want to switch to TypeScript or do you want to maintain two languages in your project?"

By the way with TypeScript it is quite easy to switch step by step, because you can enhance a single file and keep the others in JavaScript, but you have to do it structured. For example in OL I would start with the event emitter, because it doesn't have any dependence. After that you can rewrite the files with dependencies on the event-emitter and so on...

[jumpinjackie]

I've already made such a JSDoc plugin to auto-generate d.ts files from JSDoc documentation.

https://github.com/jumpinjackie/jsdoc-typescript-plugin

An example of openlayers.d.ts generated by this plugin:

https://github.com/jumpinjackie/jsdoc-typescript-plugin/blob/master/typings/openlayers.baseline.d.ts

I've been using it to generate typings for OpenLayers in my own projects for many releases now.

Despite the name suggesting it's a general purpose plugin, sadly it is not. It's just handles the OpenLayers case, which it handles very well.

[tschaub]

Our current plan is this:

• migrate from type annotations for the Closure Compiler to TypeScript annotations in comments - this is similar to what webpack is doing (see Add TypeScript type checking  webpack/webpack#6862 and subsequent work)
• consider authoring in TypeScript

We're not going to block the 5.0 release on this, so I'll remove the milestone.